Cline rules

1---
2glob: "**/*.ts"
3description: "Langgraph Project Overview & Architecture"
4---
5 
6# Project Overview
7 
8## Purpose
9 
10This project is a sophisticated LangGraph.js application designed to build and orchestrate stateful, multi-actor AI agents. Its core purpose is to automate complex software development tasks and provide advanced AI assistance within a VS Code environment. Leveraging the LangChain.js ecosystem, it focuses on defining flexible control flows for LLM-powered systems, managing state, and enabling features like persistence, human-in-the-loop interactions, and streaming.
11 
12## Core Components
13 
14* **StateGraph (LangGraph):** The foundational element for orchestrating agent workflows, modeling application flow as a graph with nodes (agents/functions) and edges (transitions), enabling complex, looping, and parallel execution paths.
15* **Agents:** Specialized AI entities responsible for distinct tasks, orchestrated by a central supervisor.
16  * **Supervisor:** Directs flow between specialized agents based on current state and user intent.
17  * **Chat Agent (`chatNode`):** Handles general conversational responses and acts as a fallback.
18  * **React Agent (`reactAgent`):** A general-purpose tool-calling agent for reasoning and acting using external tools.
19  * **Research Agent (`researchCollectNode`, `researchSummarizeNode`, `researchReportNode`):** Performs web searches, collects data, summarizes, and generates reports.
20  * **Documentation Agent (`draftDocumentationNode`, `finalizeDocumentationNode`):** Drafts and finalizes technical documentation.
21  * **Other Agents:** Support for additional agent types (e.g., `crag_agent`, `data_agent`, `master_agent`, `reflection_agent`, `rewoo_agent`, `plan_execute_agent`, `self_rag_agent`, `collaboration_agent`, `research_team`, `document_writing_team`) is indicated by the project structure.
22* **State Management (`src/agent/state.ts`):** Defines the `AgentState` interface and `AgentAnnotation` for managing conversation context, messages, user input, and agent-specific data (e.g., `query`, `research_data`, `summary`, `report`, `documentation`) using atomic state updates via reducers.
23* **Tools (`src/tools/`):** A comprehensive collection of specialized tools enabling agents to interact with external systems and perform tasks:
24  * `calculator.ts`: Performs mathematical operations.
25  * `document_processing.ts`: Handles DOCX, CSV, XML, and general text files.
26  * `exa.ts`: Integrates with the Exa API for web searches.
27  * `github.ts`: GitHub API interactions (repos, file content, issues/PRs).
28  * `local_git.ts`: In-memory Git operations (cloning, reading, committing).
29  * `tavily.ts`: Advanced web searches via Tavily Search API.
30  * `web_scraping.ts`: Extracts text/HTML from URLs and performs web crawls.
31* **Memory (`src/memory/`):** Manages conversation history, vector stores for embeddings, and checkpointing, ensuring persistent context and long-term knowledge retention, primarily via MongoDB integration.
32* **Configuration (`src/config/`):** Handles LLM provider setup (Google Generative AI), error handling, and logging.
33 
34## Key Architectural Decisions
35 
36* **Graph-based Orchestration:** Leveraging LangGraph's `StateGraph` for complex, stateful agent workflows, enabling dynamic routing, multi-agent collaboration, and advanced decision-making.
37* **Modular Agent Design:** Agents are distinct nodes in the graph, promoting clear separation of concerns, reusability, and maintainability.
38* **Tool-Use Driven:** Agents extensively use external tools for actions and information gathering, extending capabilities beyond pure language generation.
39* **Persistent Memory & State:** MongoDB integration ensures conversation continuity, long-term memory, and fault tolerance through checkpointing and dedicated stores.
40* **TypeScript:** Strong typing enhances code quality and maintainability.
41* **Streaming-First Design:** Supports various streaming modes (`values`, `updates`, `messages`, `custom`) for enhanced user experience and real-time feedback.
42* **Human-in-the-Loop (HIL):** Integrates human intervention at key decision points for approvals, state editing, and dynamic input collection.
43* **Dynamic Configuration:** `RunnableConfig` allows runtime parameterization of models, user IDs, and other settings for flexible deployment and personalized agent behavior.
44 
45## Tech Stack
46 
47* **Core Frameworks:** LangGraph.js (`@langchain/langgraph`), LangChain.js (`langchain`, `@langchain/core`, `@langchain/community`).
48* **Language:** TypeScript.
49* **AI Models:** Google Generative AI (`@langchain/google-genai`) for chat (Gemini 2.5 Pro) and embeddings (Gemini Embedding Exp 03-07).
50* **Database/Storage:** MongoDB (`@langchain/mongodb`) for persistence (checkpoints, chat history, vector stores).
51* **Web Search/Scraping:** Exa (`exa-js`, `@langchain/exa`), Tavily (`@langchain/tavily`), Cheerio (`cheerio`), Crawlee (`crawlee`).
52* **Document Processing:** Mammoth (`mammoth`), Papaparse (`papaparse`), XML2js (`xml2js`).
53* **Version Control (In-memory):** Isomorphic-git (`isomorphic-git`), Memfs (`memfs`).
54* **GitHub Integration:** Octokit (`octokit`).
55* **Logging:** Winston (`winston`).
56* **Build/Dev Tools:** Node.js, npm, Jest (`jest`), ESLint (`eslint`), Prettier (`prettier`), TypeScript Compiler (`tsc`), dotenv (`dotenv`), jiti (`jiti`).
57* **Utilities:** mathjs (`mathjs`), uuid (`uuid`), zod (`zod`), zod-to-json-schema (`zod-to-json-schema`).
58* **UI/Visualization:** React Flow (`@xyflow/react`), d3 (`d3`), recharts (`recharts`), mermaid (`mermaid`).
59 
60## Long-Term Project Goals: LangGraph.js Evolution and SFT Roadmap
61 
62This section outlines the strategic plan for enhancing this LangGraph.js application, focusing on architectural evolution, best practices, and the development of a Supervised Fine-Tuning (SFT) pipeline.
63 
64### Phase 1: Modularizing and Scaling with Multi-Graph Architectures
65 
66**Goal:** Transition from a monolithic single graph to a modular, scalable multi-agent system using LangGraph's advanced features.
67 
68#### Actionable Steps
69 
70* **Subgraphs:**
71  * Identify logical boundaries within the current single graph to extract into independent subgraphs (e.g., separate subgraphs for research, documentation drafting, tool execution).
72  * Implement subgraphs using `StateGraph` and compile them.
73  * Integrate subgraphs into the main supervisor graph using `addNode("subgraph_name", compiled_subgraph)` for shared state, or a wrapper node for state transformation if schemas differ.
74* **Multi-Agent Systems:**
75  * Design a clear routing mechanism (e.g., an LLM-based router node in the supervisor) to intelligently direct tasks to the appropriate specialized agent/subgraph.
76  * Implement agents (nodes) with clear responsibilities and defined inputs/outputs.
77  * Utilize the `Command` primitive within agent nodes for explicit handoffs (`return new Command({ goto: "next_agent_node", update: { ... } })`) to combine state updates and control flow between agents.
78* **Functional API Integration (Optional but Recommended):**
79  * Refactor existing complex node logic into smaller, testable `task` functions.
80  * Use `entrypoint()` to orchestrate sequences of `task()` functions for simpler, checkpointable workflows within nodes.
81 
82### Phase 2: Implementing Advanced LangGraph Best Practices
83 
84**Goal:** Enhance the robustness, observability, and user experience of your LangGraph application by applying core best practices.
85 
86#### Actionable Steps To Implement
87 
88* **Persistence & Memory Management:**
89  * Integrate `MongoDBStore` (or another persistent store like PostgresSaver) for cross-thread long-term memory (e.g., user preferences, accumulated research data).
90  * Design clear namespaces and keys for `Store` entries to organize memories effectively.
91  * Implement semantic search for memory retrieval using embeddings (e.g., `GoogleGenerativeAIEmbeddings`).
92* **Human-in-the-Loop (HIL):**
93  * Identify critical decision points or sensitive actions (e.g., external API calls, final output generation) where human intervention is desired.
94  * Implement `interrupt()` functions at these points to pause execution and allow human review/input.
95  * Utilize `Command({ resume: ... })` to resume execution with human-provided data, or `Command({ goto: ..., update: ... })` for dynamic routing based on human feedback.
96* **Streaming & Responsiveness:**
97  * Implement `streamMode: "messages"` when invoking graphs to stream LLM tokens for real-time model output.
98  * Implement `streamMode: "custom"` with `config.writer?.(chunk)` within nodes to stream custom progress updates (e.g., "Fetching data...", "Analyzing results...").
99  * Combine multiple `streamMode` options (`streamMode: ["messages", "custom", "updates"]`) for comprehensive real-time feedback.
100* **Robust Error Handling:**
101  * Implement specific `try-catch` blocks within tool invocation nodes to gracefully handle tool execution errors.
102  * Define custom error states or fallback nodes in the graph to manage and recover from errors (e.g., retry logic, escalating to a human agent).
103  * Consider using `NodeInterrupt` for dynamic interruption based on specific error conditions within nodes (though `interrupt()` is generally preferred for direct HIL).
104* **Configuration Management:**
105  * Parameterize LLM models, system prompts, API keys, and other dynamic settings using `RunnableConfig`.
106  * Access `config.configurable` within nodes to dynamically select models or adjust behavior based on runtime parameters.
107  * Define `Annotation` schemas for configurable parameters for type safety and clarity.
108* **Node Caching:**
109  * Identify expensive or frequently re-executed nodes (e.g., complex computations, external API calls) that produce deterministic outputs.
110  * Implement caching for these nodes using `cachePolicy` in `addNode` and a `checkpointer` with a cache backend (e.g., `InMemoryCache`).
111 
112### Phase 3: Dataset Creation for SFT with Gemini-2.5-Flash
113 
114**Goal:** Generate a high-quality dataset from agent interactions for Supervised Fine-Tuning (SFT) of a Gemini-2.5-Flash model.
115 
116#### Actionable Steps To Finish
117 
118* **LangSmith Integration for Data Collection:**
119  * Ensure `LANGCHAIN_TRACING_V2=true` and `LANGCHAIN_PROJECT="Your_Project_Name"` are set in your environment variables to automatically trace all LangGraph runs to LangSmith.
120  * Run a variety of interactions with your improved LangGraph agent, covering diverse user queries, tool uses, multi-turn dialogues, and scenarios where agents might make mistakes.
121* **Data Curation and Extraction from LangSmith:**
122  * Regularly review traces in the LangSmith UI.
123  * Identify successful interaction patterns where the agent performs optimally, and also instances where the agent initially struggles but eventually recovers or is corrected by human intervention (these are valuable for SFT).
124  * Use LangSmith's export functionality to download selected traces as a dataset. For SFT, you will likely need to extract clear input-output pairs from these traces.
125    * **For Chat-based SFT:** Extract sequences of `HumanMessage` and `AIMessage` pairs, potentially including `ToolMessage` outputs as part of the `AIMessage` content if the fine-tuning format supports it.
126    * **For Tool-Use SFT:** Extract prompts that lead to desired tool calls, and the corresponding tool call arguments, as input-output pairs.
127* **Dataset Pre-processing and Formatting:**
128  * Consult Google's official documentation for the exact SFT data format requirements for Gemini models (e.g., JSONL format with "prompt" and "completion" fields, or a structured message list format).
129  * Clean and filter the extracted data: remove irrelevant messages, correct any agent errors (if aiming for perfect examples), and ensure consistency.
130  * For complex multi-turn conversations, consider summarizing or segmenting the conversation to create focused SFT examples.
131* **Embedding Data for Semantic Search (if applicable):**
132  * If your SFT involves improving retrieval or memory components, ensure your dataset includes relevant text segments and their corresponding embeddings.
133  * Use `GoogleGenerativeAIEmbeddings` (`gemini-embedding-exp-03-07` model, 768 dimensions) to generate embeddings for your text data, matching the embedding model used in your production agent.
134* **Iterative Refinement and Evaluation:**
135  * Start with a small, high-quality dataset for initial SFT.
136  * After fine-tuning, evaluate the new Gemini-2.5-Flash model's performance using LangSmith's evaluation capabilities against a held-out test set.
137  * Continuously gather new interaction data, curate, and add to your SFT dataset to further improve model performance over time.
138 
139This plan aims to guide you through enhancing your LangGraph.js application and building a robust SFT pipeline for your Gemini-2.5-Flash model.
140