{"id":47941587,"url":"https://github.com/8thlight/ai-pocket-projects-langstack","last_synced_at":"2026-04-04T08:08:47.929Z","repository":{"id":318767529,"uuid":"1076466889","full_name":"8thlight/ai-pocket-projects-langstack","owner":"8thlight","description":"AI Pocket Projects for the LangStack (LangChain / LangGraph / LangSmith)","archived":false,"fork":false,"pushed_at":"2025-10-14T23:53:36.000Z","size":19534,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-15T04:04:41.662Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"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/8thlight.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-10-14T22:49:00.000Z","updated_at":"2025-10-14T23:36:58.000Z","dependencies_parsed_at":"2025-10-15T11:18:43.114Z","dependency_job_id":"ddde3873-8e7b-4c2d-a0f7-527174f36330","html_url":"https://github.com/8thlight/ai-pocket-projects-langstack","commit_stats":null,"previous_names":["8thlight/ai-pocket-projects-langstack"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/8thlight/ai-pocket-projects-langstack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/8thlight%2Fai-pocket-projects-langstack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/8thlight%2Fai-pocket-projects-langstack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/8thlight%2Fai-pocket-projects-langstack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/8thlight%2Fai-pocket-projects-langstack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/8thlight","download_url":"https://codeload.github.com/8thlight/ai-pocket-projects-langstack/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/8thlight%2Fai-pocket-projects-langstack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31392217,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T04:26:24.776Z","status":"ssl_error","status_checked_at":"2026-04-04T04:23:34.147Z","response_time":60,"last_error":"SSL_read: 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":[],"created_at":"2026-04-04T08:08:47.392Z","updated_at":"2026-04-04T08:08:47.899Z","avatar_url":"https://github.com/8thlight.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🎯 AI Pocket Projects - LangStack Edition (LangChain, LangGraph, LangSmith)\n\nThis implementation is based on the [8th Light AI Pocket Projects](https://github.com/8thlight/ai-pocket-projects) and [Travis' AI Agent Demo](https://github.com/T-rav/ai-agent-demo)\n\n\u003e Agentic chat flow powered by LangGraph, with standard and deep research modes.\n\n## 🗺️ Documentation Structure\n\n```\n├── README.md                      # This file - overview and navigation\n├── 1-SIMPLE-UI.md                 # Building the React frontend\n├── 2-INGEST-PIPELINE.md           # Document ingestion process (do this first!)\n├── 3-RAG-IMPLEMENTATION.md        # RAG system with intelligent routing\n└── 4-RESEARCH-WORKFLOWS.md        # Multi-agent research orchestration\n```\n\n## 🏗️ Architecture Overview\n\n### System Components\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                        User Interface                        │\n│                   (React + TypeScript)                       │\n└────────────────────────┬────────────────────────────────────┘\n                         │ HTTP/SSE\n┌────────────────────────▼────────────────────────────────────┐\n│                      FastAPI Backend                         │\n│                                                              │\n│  ┌──────────────────────────────────────────────────────┐  │\n│  │             LangGraph Agent (RAGAgent)               │  │\n│  │                                                      │  │\n│  │  ┌────────┐  ┌──────────┐  ┌──────────────────┐   │  │\n│  │  │ Router │→│ Simple    │  │ Research         │   │  │\n│  │  │        │  │ RAG Path │  │ Multi-Agent Path │   │  │\n│  │  └────────┘  └──────────┘  └──────────────────┘   │  │\n│  └──────────────────────────────────────────────────────┘  │\n└─────────────────────────┬───────────────────────────────────┘\n                          │\n          ┌───────────────┼───────────────┐\n          │               │               │\n┌─────────▼──────┐ ┌─────▼──────┐ ┌─────▼─────┐\n│   Pinecone     │ │   OpenAI   │ │  Tavily   │\n│ Vector Store   │ │  GPT-4/4o  │ │Web Search │\n└────────────────┘ └────────────┘ └───────────┘\n```\n\n### LangGraph Workflow\n\n```\n                    ┌─────────┐\n                    │  Start  │\n                    └────┬────┘\n                         │\n                    ┌────▼────┐\n                    │ Router  │\n                    └────┬────┘\n                         │\n           ┌─────────────┴─────────────┐\n           │                           │\n      [simple]                    [research]\n           │                           │\n    ┌──────▼──────┐           ┌────────▼─────────┐\n    │ Simple RAG  │           │ Research Planner │\n    │   (Auto)    │           │   (Plan topics)  │\n    └──────┬──────┘           └────────┬─────────┘\n           │                           │\n    ┌──────▼────────┐                 │\n    │ Simple Agent  │          ┌──────▼──────────┐\n    │ (Answer+Web)  │          │ Research        │\n    └──────┬────────┘          │ Gatherer        │\n           │                   │ (KB + Web)      │\n      [tool_call?]             └──────┬──────────┘\n           │                          │\n       ┌───┴───┐              [gather_more?]\n       │       │                      │\n    [yes]    [no]              ┌──────┴─────┐\n       │       │               │            │\n  ┌────▼──┐   │         [more needed]  [complete]\n  │ Tools │   │               │            │\n  └────┬──┘   │          ┌────▼───┐   ┌────▼────────┐\n       │      │          │ Tools  │   │   Report    │\n       └──────┤          └────┬───┘   │   Builder   │\n              │               │        │ (Synthesis) │\n         ┌────▼────┐          │        └────┬────────┘\n         │   END   │          └─────────────┘\n         └─────────┘                   │\n                               ┌───────▼────┐\n                               │     END    │\n                               └────────────┘\n```\n\n## 🎓 Learning Path\n\n### AI-Assisted Development\n\nThis codebase is designed to be explored and extended using AI coding assistants (Cursor, Claude, GitHub Copilot). Specifically the first phase can be completly without looking at the code. \n\n### Recommended Reading Order\n\n1. **UI First**: `1-SIMPLE-UI.md` - Build the React frontend interface with mock data\n2. **Data Foundation**: `2-INGEST-PIPELINE.md` - Get your documents into the system\n3. **Core RAG**: `3-RAG-IMPLEMENTATION.md` - Simple Q\u0026A with citations\n4. **Advanced Flows**: `4-RESEARCH-WORKFLOWS.md` - Multi-agent research orchestration with citations\n\n## 🔑 Key Concepts\n\n### Intelligent Routing\nThe system uses GPT-4o-mini to classify queries:\n- **Simple**: Direct questions → Fast RAG retrieval + answer\n- **Research**: Complex topics → Multi-agent research workflow\n\n### Context Engineering\nCompress retrieved context to fit model limits without losing citations or key facts.\n\n- **Objectives**: maximize signal per token, preserve citation anchors, keep readability\n- **Techniques**\n  - Query-focused summarization (extract salient sentences; keep inline quotes where helpful)\n  - Rerank → deduplicate similar chunks before compression\n  - Citation-preserving compression: keep `document_title`, `file_name`, `chunk_index`, `doc_id`\n  - Structure-aware trimming: prefer headings, bullet points, tables over raw prose\n- **Mode policy**\n  - Simple: small k (e.g., 3–5), light extractive compression, no cross-source synthesis\n  - Research: larger k, per-source summaries + merged synthesis; retain `[KB‑n]`/`[WEB‑n]` tags\n- **Implementation hooks**\n  - Pre-answer: `rerank(top_k) → dedupe → compress(query)` with token budget guard\n  - Budget controls: `max_context_tokens`, `per_source_min_tokens`\n  - Observability: log pre/post token counts and kept/dropped sources in traces\n\n### Multi-Agent Research\nComplex queries trigger a 3-phase agent workflow:\n1. **Planner**: Breaks down topic into subtopics and research questions\n2. **Gatherer**: Searches knowledge base + web for information\n3. **Report Builder**: Synthesizes findings into comprehensive markdown report\n\n### Mandatory Citations\nEvery response includes source attribution:\n- **Knowledge Base**: `[KB-1]`, `[KB-2]` with file references\n- **Web Sources**: `[WEB-1]`, `[WEB-2]` with URLs\n- UI automatically displays expandable source cards\n\n### LangSmith Observability\nAll agent interactions are traced:\n- View LLM calls and token usage\n- Inspect tool invocations\n- Debug workflow decisions\n- Evaluate prompt performance\n\n## 🛠️ Tech Stack\n\n| Component | Technology | Purpose |\n|-----------|-----------|---------|\n| **Agent Orchestration** | LangGraph | Multi-agent workflow state management |\n| **LLM Framework** | LangChain | Tool binding, message handling, abstractions |\n| **Language Models** | OpenAI GPT-4/4o/4o-mini | Generation, routing, synthesis |\n| **Embeddings** | OpenAI text-embedding-3-small | Document vectorization |\n| **Vector Store** | Pinecone | Semantic search and retrieval |\n| **Web Search** | Tavily | Real-time information gathering |\n| **Observability** | LangSmith | Tracing, monitoring, evaluation |\n| **Backend** | FastAPI | REST API + SSE streaming |\n| **Frontend** | React + TypeScript | User interface |\n\n### Build It Step-by-Step\n\nThis is a **learning-first** approach optimized for AI-assisted development:\n\n1. **`1-SIMPLE-UI.md`** - Get a working interface up quickly\n2. **`2-INGEST-PIPELINE.md`** - Load your knowledge base (critical first step!)\n3. **`3-RAG-IMPLEMENTATION.md`** - Wire up retrieval and simple Q\u0026A\n4. **`4-RESEARCH-WORKFLOWS.md`** - Add multi-agent research capabilities\n\nEach guide focuses on **concepts and direction** rather than copy-paste code - designed for exploration with your AI assistant.\n\n## 📚 References\n\n- [8th Light AI Pocket Projects](https://github.com/8thlight/ai-pocket-projects) - Original learning path\n- [LangGraph Documentation](https://langchain-ai.github.io/langgraph/) - Agent orchestration\n- [LangChain Documentation](https://python.langchain.com/) - LLM framework\n- [LangSmith Documentation](https://docs.smith.langchain.com/) - Observability platform\n\n---\n\n**Ready to dive in?** Start with `1-SIMPLE-UI.md` to build your interface, then `2-INGEST-PIPELINE.md` to load your knowledge base!\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F8thlight%2Fai-pocket-projects-langstack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F8thlight%2Fai-pocket-projects-langstack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F8thlight%2Fai-pocket-projects-langstack/lists"}