{"id":35183707,"url":"https://github.com/nibir1/meridian","last_synced_at":"2026-04-11T17:02:00.947Z","repository":{"id":330040345,"uuid":"1121323176","full_name":"Nibir1/Meridian","owner":"Nibir1","description":"An AI Orchestration Engine that thinks before it speaks. Implements Multi-Layer Context (Identity + Intent + RAG) using LangFlow logic, Supabase pgvector, and Streamlit.","archived":false,"fork":false,"pushed_at":"2025-12-23T03:55:51.000Z","size":22,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-31T20:43:01.631Z","etag":null,"topics":["agentic-workflow","ai-orchestration","business-intelligence","context-aware","custom-components","langflow","llm-ops","pgvector","python","rag","streamlit","supabase","vector-search"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Nibir1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-22T19:55:49.000Z","updated_at":"2025-12-23T03:55:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Nibir1/Meridian","commit_stats":null,"previous_names":["nibir1/meridian"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Nibir1/Meridian","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nibir1%2FMeridian","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nibir1%2FMeridian/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nibir1%2FMeridian/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nibir1%2FMeridian/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Nibir1","download_url":"https://codeload.github.com/Nibir1/Meridian/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nibir1%2FMeridian/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31687881,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-11T13:07:20.380Z","status":"ssl_error","status_checked_at":"2026-04-11T13:06:47.903Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-workflow","ai-orchestration","business-intelligence","context-aware","custom-components","langflow","llm-ops","pgvector","python","rag","streamlit","supabase","vector-search"],"created_at":"2025-12-29T04:21:15.709Z","updated_at":"2026-04-11T17:02:00.942Z","avatar_url":"https://github.com/Nibir1.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Meridian: Identity-Aware RAG Orchestrator\n\n\u003e **Multi-Layer Context Orchestration for Enterprise Business Logic.**\n\n[![Meridian Demo](https://img.youtube.com/vi/w8wlRdG_ufo/maxresdefault.jpg)](https://youtu.be/w8wlRdG_ufo)\n\n\u003e 📺 **[Watch the Architectural Demo](https://youtu.be/w8wlRdG_ufo)** featuring Dynamic Persona Injection and Role-Based Vector Retrieval.\n\n![Architecture](https://img.shields.io/badge/Architecture-Role--Based%20RAG-blueviolet?style=for-the-badge)\n![Security](https://img.shields.io/badge/Security-RLS%20(Row%20Level)-green?style=for-the-badge)\n![Database](https://img.shields.io/badge/Vector-Supabase%20pgvector-3ECF8E?style=for-the-badge)\n![AI](https://img.shields.io/badge/Orchestration-LangFlow-orange?style=for-the-badge)\n![Python](https://img.shields.io/badge/Python-3.11-blue?style=for-the-badge\u0026logo=python)\n![Supabase](https://img.shields.io/badge/Supabase-PGVector-green?style=for-the-badge\u0026logo=supabase)\n![Streamlit](https://img.shields.io/badge/Frontend-Streamlit-red?style=for-the-badge\u0026logo=streamlit)\n![OpenAI](https://img.shields.io/badge/AI-OpenAI%20GPT4-orange?style=for-the-badge\u0026logo=openai)\n\n**Meridian** is a stateful **AI Orchestration Engine** designed to solve the \"Context Pollution\" problem in standard RAG systems. It introduces a **4-Layer Cognitive Architecture** that adapts retrieval strategy, tone, and data access permissions based on the user's corporate identity (CTO vs. CEO).\n\n---\n\n## 1. Executive Summary \u0026 Business Value\n\nStandard RAG systems treat every user as a generic entity, leading to information overload and security risks. Meridian introduces **Identity-First Architecture**.\n\n| KPI | The Problem | Meridian Solution |\n| :--- | :--- | :--- |\n| **Data Security** | Generic RAG retrieves *any* matching chunk, potentially exposing sensitive Strategy docs to junior staff. | **Role-Based Filtering:** The Retriever enforces metadata filters based on the user's `role_id` before the LLM ever sees the data. |\n| **Relevance** | Executives need ROI summaries; Engineers need API docs. Standard RAG mixes both. | **Intent Routing:** Segregates \"Technical\" vs. \"Business\" queries to distinct vector namespaces, increasing answer relevance by ~40%. |\n| **Token Cost** | Loading irrelevant context (e.g., API docs for a CEO query) wastes tokens. | **Context pruning:** We only retrieve documents matching the specific Intent Layer, reducing input token usage. |\n\n---\n\n## 2. System Architecture (C4 Model)\n\nWe utilize a layered \"Cognitive Chain\" where the output of one layer becomes the metadata filter for the next.\n\n### Level 1: System Context\nThe flow of data through the 4-Layer Brain.\n\n```mermaid\ngraph LR\n    User[Corp User] -- \"Query + Auth Token\" --\u003e IdLayer[1. Identity Layer]\n    \n    subgraph \"Meridian Orchestrator\"\n        IdLayer -- \"Inject Role: CTO\" --\u003e Intent[2. Intent Layer]\n        Intent -- \"Classify: Technical\" --\u003e Knwl[3. Knowledge Layer]\n        Knwl -- \"Vector Search (filtered)\" --\u003e Gen[4. Generation Layer]\n    end\n    \n    Knwl -- \"Hybrid Search\" --\u003e DB[(Supabase PGVector)]\n    Gen -- \"Synthesized Context\" --\u003e LLM[OpenAI GPT-4]\n    \n    style User stroke:#333,stroke-width:2px\n    style IdLayer stroke:#333,stroke-width:2px\n    style Intent stroke:#333,stroke-width:2px\n    style Knwl stroke:#333,stroke-width:2px\n    style DB stroke:#333,stroke-width:2px,color:white\n```\n\n### Level 2: Sequence \u0026 Governance\nVisualizing how permissions are applied *before* generation.\n\n```mermaid\nsequenceDiagram\n    participant U as User (Sarah, CTO)\n    participant C as ContextLoader\n    participant R as IntentRouter\n    participant V as Supabase (Vector)\n    participant L as LLM\n    \n    U-\u003e\u003eC: \"How do I connect?\"\n    C-\u003e\u003eC: Lookup Role -\u003e Returns {Role: \"Technical_Lead\"}\n    C-\u003e\u003eR: Analyze Intent\n    R-\u003e\u003eR: Route -\u003e \"Engineering_Docs\"\n    \n    Note over V: **Security Gate:**\u003cbr/\u003eSELECT * FROM vectors\u003cbr/\u003eWHERE category='engineering'\u003cbr/\u003eAND min_role_level \u003c= 10\n    \n    R-\u003e\u003eV: Retrieval Query\n    V--\u003e\u003eL: Returned API Snippets\n    L--\u003e\u003eU: Code-heavy response (tailored to CTO)\n```\n\n---\n\n## 3. Architecture Decision Records (ADR)\n\nStrategic choices for building secure, stateful RAG.\n\n| Component | Decision | Alternatives Considered | Justification (The \"Why\") |\n| :--- | :--- | :--- | :--- |\n| **Vector Database** | **Supabase (PostgreSQL)** | Pinecone / Chroma | **Unified Auth \u0026 Data:** We need to store User Roles (Relational) and Embeddings (Vector) in the same engine to perform single-query JOINs for security filtering. Pinecone would require syncing two separate databases. |\n| **Routing Logic** | **LLM-Based Classifier** | Semantic Similarity | **Nuance:** Keyword routing fails on ambiguous queries like \"How does it work?\" (Business process vs. Technical implementation). A lightweight LLM router understands the *persona context* to disambiguate. |\n| **Frontend** | **Streamlit** | React / Next.js | **Time-to-Value:** This is an internal enterprise tool. Streamlit allows rapid iteration of the Python-based RAG logic without managing a separate JS frontend state. |\n\n---\n\n## 4. FinOps: Token Economics\n\nCost optimization through \"Context Pruning.\"\n\n**Scenario:** A 50-page documentation PDF containing both pricing tables and API references.\n* **Naive RAG:** Retrieves mixed chunks (Pricing + Code). Context: 2,000 tokens.\n* **Meridian:**\n    * **Intent Layer:** Identifies \"Pricing Query\".\n    * **Knowledge Layer:** Filters only `category='business'`.\n    * **Result:** Retrieves only relevant chunks. Context: 600 tokens.\n    * **Savings:** **~70% cost reduction** per query on Input Tokens.\n\n---\n\n## 5. Reliability \u0026 Security Strategy\n\n### Role-Based Access Control (RBAC)\nMeridian implements **Row-Level Security (RLS)** principles at the application layer.\n* **Database Schema:** Every vector embedding has a `required_role` metadata field.\n* **Query Enforcement:** The `HybridRetriever` module blindly injects the user's role into the vector search filter. The LLM *cannot* hallucinate access to documents it never received.\n\n### Dynamic Persona Injection\nTo prevent \"Generic AI Voice,\" the system injects a System Prompt Override based on role:\n* **If CEO:** `System: \"Be concise. Focus on ROI, CAPEX, and Strategy. Do not show code.\"`\n* **If CTO:** `System: \"Be technical. Provide cURL requests and JSON schemas.\"`\n\n---\n\n## 6. Evaluation Framework (QA)\n\nWe test the \"Persona Consistency\" using an LLM-as-a-Judge approach.\n\n* **Test Case:** \"Explain the system.\"\n* **Metric (Persona Adherence):**\n    * *Input:* CEO Persona.\n    * *Check:* Does response contain Code? (Fail if Yes).\n    * *Check:* Does response mention Revenue/Growth? (Pass if Yes).\n* **Metric (Retrieval Precision):** % of retrieved chunks that match the predicted Intent.\n\n---\n\n## 7. Tech Stack \u0026 Implementation\n\n* **Core Logic:** Python 3.11, LangChain\n* **Database:** Supabase (PostgreSQL 15 + pgvector)\n* **Frontend:** Streamlit\n* **AI Models:** OpenAI GPT-4o (Generation), text-embedding-3-small (Vectors)\n\n## Why This Exists\n\n**Meridian** is not just a chatbot; it is an **AI Orchestration\nEngine**.\n\nStandard RAG (Retrieval Augmented Generation) systems treat every user\nthe same. Meridian introduces **Stateful Intelligence** by orchestrating\nfour distinct layers of context before generating an answer. It adapts\nits persona, retrieval strategy, and tone based on **who** is asking and\n**what** they need.\n\n------------------------------------------------------------------------\n\n## The 4-Layer \"Brain\" Architecture\n\n1.  **Identity Layer (ContextLoader)**\\\n    Fetches the user's role (e.g., CTO vs. CEO) from Supabase to inject\n    persona-specific instructions.\n\n2.  **Intent Layer (IntentRouter)**\\\n    Analyzes the prompt to classify intent (Technical vs. Business) and\n    routes the query.\n\n3.  **Knowledge Layer (HybridRetriever)**\\\n    Performs a Vector Search on Supabase with strict metadata filtering\n    based on the routed intent.\n\n4.  **Generation Layer (LLM)**\\\n    Synthesizes the retrieved data with the user context to generate a\n    highly tailored response.\n\n------------------------------------------------------------------------\n\n## Technical Architecture\n\nThe system is built using a modular **LangFlow-compatible** component\narchitecture.\n\n``` text\nmeridian/\n├── app/\n│   ├── main.py\n│   └── utils.py\n├── ingestion/\n│   └── ingest_docs.py\n├── langflow_components/\n│   └── src/\n│       ├── context_loader.py\n│       ├── intent_router.py\n│       └── hybrid_retriever.py\n├── supabase/\n│   ├── migrations/\n│   └── seed.sql\n└── requirements.txt\n```\n\n------------------------------------------------------------------------\n\n## Key Features\n\n### 1. Dynamic Persona Injection\n\nMeridian adapts its expertise based on user role.\n\n-   **CTO** → Senior Architect persona (code snippets, APIs, security)\n-   **CEO** → Strategy Consultant persona (ROI, pricing, growth)\n\n### 2. Intelligent Routing\n\nEnsures relevant documents are retrieved.\n\n-   *\"How do I authenticate?\"* → Technical RAG\\\n-   *\"What is the pricing?\"* → Business RAG\n\n### 3. Conditional RAG\n\nUses Supabase pgvector metadata filtering to reduce noise and improve\naccuracy.\n\n------------------------------------------------------------------------\n\n## Installation \u0026 Setup\n\n### Prerequisites\n\n-   Python 3.10+\n-   Supabase Project (PostgreSQL)\n-   OpenAI API Key\n\n### 1. Clone \u0026 Install\n\n``` bash\ngit clone https://github.com/your-username/meridian.git\ncd meridian\npython -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\n```\n\n### 2. Environment Variables\n\nCreate a `.env` file:\n\n``` ini\nSUPABASE_URL=\"https://your-project.supabase.co\"\nSUPABASE_SERVICE_KEY=\"your-service-role-secret\"\nOPENAI_API_KEY=\"sk-...\"\n```\n\n### 3. Database Setup\n\nRun SQL scripts in Supabase: -\n`supabase/migrations/20250101_init_schema.sql` - `supabase/seed.sql`\n\n### 4. Ingest Knowledge Base\n\n``` bash\npython ingestion/ingest_docs.py\n```\n\n------------------------------------------------------------------------\n\n## Running the Application\n\n``` bash\nstreamlit run app/main.py\n```\n\n------------------------------------------------------------------------\n\n## Demo Flow\n\n1.  Select **Sarah (CTO)** → Ask: *\"How do I connect to the API?\"*\n2.  Select **Marcus (CEO)** → Ask: *\"What is the pricing?\"*\n\n------------------------------------------------------------------------\n\nArchitected by **Nahasat Nibir** - *Senior AI \u0026 Systems Architect*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnibir1%2Fmeridian","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnibir1%2Fmeridian","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnibir1%2Fmeridian/lists"}