| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 6 | 6 | 0% |
| Commands | 0 | 0 | 12 | 0% |
| Section tags | 1 | 0 | 6 | 14% |
What each file covers
Sections
0 shared · 6 only in A · 6 only in B- − Subgraphs and Workflow Orchestration
- − LangGraph Core Concept
- − Key Components
- − Designing Subgraphs
- − Example Flows
- − Persistence with Subgraphs
- + Development Guidelines
- + Coding Standards
- + Best Practices
- + Tooling and Environment
- + Collaboration and Workflow
- + Testing Philosophy
Commands
0 shared · 0 only in A · 12 only in B- + prettier
- + eslint.config.ts
- + eslint
- + npm run lint
- + npm run format:check
- + npm
- + jest
- + tsc
- + npm run build
- + npm run test
- + npm run test:int
- + npm run test:all
Section tags
1 shared · 0 only in A · 6 only in B- + setup
- + build
- + test
- + lint-format
- + code-style
- + security
- agent-behaviour
Line diff
ssdeanx/langgraph-dm · .clinerules/subgraphs.md
@@ −1 @@
1---
2glob: "**/*.ts"
3description: "Langgraph Subgraphs & Workflow Orchestration"
4---
5# Subgraphs and Workflow Orchestration
6
7## LangGraph Core Concept
8
9* This project heavily utilizes LangGraph's `StateGraph` to define and manage complex, multi-step AI agent workflows.
10* A "graph" represents the flow of control and data between different nodes (which are typically agents or tool calls).
11* Subgraphs allow you to reuse an existing graph as a node within another graph, promoting modularity and hierarchical organization.
12
13## Key Components
14
15* **Nodes:** Represent individual steps or agents in the workflow (e.g., `entryNode`, `supervisor`, `reactAgent`, `research_collectNode`). Each node takes the current `AgentState` as input and returns an updated state.
16* **Edges:** Define the transitions between nodes.
17 * **Normal Edges:** Unconditionally move from one node to another (e.g., `START` to `entry`, `chat` to `END`).
18 * **Conditional Edges:** Route to different nodes based on a decision function (e.g., `routeMessages` from `supervisor` to various agents). The routing function takes the `AgentState` and returns the name of the next node(s) or `END`.
19* **`AgentState`:** The central data structure that is passed and modified across all nodes in the graph, maintaining the conversation context and agent-specific data. Defined using `Annotation`.
20* **Supervisor:** A critical node responsible for intelligently routing the `AgentState` to the appropriate specialized agent or action based on the current context and goal.
21* **`Command` Primitive:** Allows combining state updates and control flow (routing) within a single node, useful for dynamic handoffs between agents.
22
23## Designing Subgraphs
24
25* **Modularity:** Complex workflows should be broken down into smaller, manageable subgraphs or sequences of nodes.
26* **Clear Responsibilities:** Each node and subgraph should have a clear, single responsibility.
27* **State Flow:** Pay close attention to how data flows through the `AgentState` between nodes to ensure necessary information is available at each step.
28* **Error Handling:** Design subgraphs to handle errors gracefully, potentially returning control to a supervisor for re-routing or error reporting.
29* **Routing Logic:** The `routeMessages` function (or similar conditional routing) is crucial for dynamic and intelligent workflow execution. Ensure its logic covers all necessary transitions and fallback scenarios.
30* **Communication:**
31 * If the parent graph and subgraph share schema keys (channels), the compiled subgraph can be added directly as a node.
32 * If schemas are different, define a node function that explicitly invokes the subgraph, transforming input state and output results to match the parent's schema. This prevents errors due to non-overlapping channels.
33* **Nesting:** Subgraphs can be nested to any level, allowing for highly complex hierarchical agent systems.
34
35## Example Flows
36
37* **General Conversation:** `entry` -> `supervisor` -> `chat` -> `END`
38* **Research Task:** `entry` -> `supervisor` -> `research_collect` -> `research_summarize` -> `research_report` -> `supervisor` (for final response)
39* **Documentation Task:** `entry` -> `supervisor` -> `draft_documentation` -> `finalize_documentation` -> `supervisor` (for final response)
40* **React Agent Task:** `entry` -> `supervisor` -> `react` -> `supervisor` (for tool execution or further action)
41* **Multi-agent Network:** Agents can communicate with each other in a many-to-many fashion, making decisions on which agent to call next (e.g., `travel_advisor` -> `sightseeing_advisor` -> `hotel_advisor`).
42
43## Persistence with Subgraphs
44
45* Checkpointers should be passed only when compiling the *parent* graph. LangGraph automatically propagates the checkpointer to child subgraphs, enabling persistence across nested levels.
46* State of subgraphs can be viewed and updated, facilitating human-in-the-loop interactions and debugging within nested workflows.
47
ssdeanx/langgraph-dm · .clinerules/development_guidelines.md
@@ +1 @@
1---
2glob: "**/*.ts"
3description: "Langgraph Development Guidelines"
4---
5
6# Development Guidelines
7
8## Coding Standards
9
10* **Language:** TypeScript. Adhere to strict type-checking and leverage TypeScript's features for robust code.
11* **Formatting:** Use Prettier (`prettier`) for consistent code formatting across the project. Ensure consistent indentation (likely 2 spaces), line endings, and brace style as configured in `eslint.config.ts`.
12* **Linting:** Follow ESLint (`eslint`) rules defined in `eslint.config.ts`. Address all linting warnings and errors before committing code. Use `npm run lint` and `npm run format:check`.
13* **Naming Conventions:** Adhere to conventional naming (camelCase for variables/functions, PascalCase for classes/interfaces) as enforced by ESLint.
14* **Modularity:** Keep functions, modules, and especially agent nodes, small and focused on a single responsibility. This promotes reusability and easier debugging.
15
16## Best Practices
17
18* **Error Handling:** Implement robust error handling, particularly for external tool calls and API interactions. Utilize custom error classes (e.g., `ToolExecutionError`, `ModelInvocationError`) and centralized error handling (e.g., `handleGlobalError` in `src/config/errors.ts`).
19* **Logging:** Utilize the `winston` logger (`src/config/logger.ts`) for consistent and informative logging across the application. Use appropriate log levels (`debug`, `info`, `error`) for different environments.
20* **Asynchronous Operations:** Use `async/await` for all asynchronous operations to maintain readability and manage control flow effectively.
21* **Configuration Management:** Manage sensitive information and API keys using environment variables (e.g., `MONGODB_ATLAS_URI`, `GOOGLE_API_KEY`, `EXA_API_KEY`, `GITHUB_TOKEN`) via `.env` files for local development. Ensure proper environment variable setup (e.g., `process.env[name]`).
22* **Tool Usage:** Ensure proper schema validation for tool inputs using `zod`. Design tools to be idempotent where possible.
23* **Graph Design:** Follow LangGraph's principles: nodes do the work, edges define the flow. Use `StateGraph` for complex state management.
24* **State Management:** Pay close attention to how state is passed and modified between nodes, leveraging `Annotation` and reducer functions for clear, predictable updates.
25* **Dependency Management:** Manage dependencies using `npm` and ensure `@langchain/core` is resolved to a single version to prevent conflicts.
26
27## Tooling and Environment
28
29* **IDE:** VS Code is the recommended development environment.
30* **Package Manager:** npm.
31* **Testing Framework:** Jest (`jest`) for unit and integration tests.
32* **Build System:** TypeScript compiler (`tsc`) for transpilation (`npm run build`).
33* **Version Control:** Git. Follow a clear branching strategy (e.g., `main` for stable code, feature branches for new development).
34* **LangSmith:** Integrate LangSmith for best-in-class observability, debugging, testing, and monitoring of LLM applications. Set `LANGSMITH_API_KEY`, `LANGCHAIN_TRACING_V2`, and `LANGCHAIN_CALLBACKS_BACKGROUND` environment variables.
35
36## Collaboration and Workflow
37
38* **Version Control:** Utilize Git for all code changes. Adhere to a branching model that supports collaborative development and code reviews.
39* **Code Reviews:** All significant code changes must undergo a thorough code review process to ensure quality, adherence to standards, and identification of potential issues.
40* **Task Management:** Consider using a `cline_todo.md` file (as suggested in `.clinerules` best practices) to track tasks and subtasks within the project, ensuring clear summaries, timestamps, and status updates.
41
42## Testing Philosophy
43
44* **Unit Tests:** Write comprehensive unit tests for individual functions, modules, and especially for agent logic and tool implementations.
45* **Integration Tests:** Develop integration tests to verify the interactions between different agents and external services within the LangGraph workflow.
46* **Test Commands:** Use `npm run test` for unit tests, `npm run test:int` for integration tests, and `npm run test:all` for running all tests and linting checks.
47* **Test-Driven Development (TDD):** Encourage a TDD approach where tests are written before the corresponding code to guide development and ensure testability.
48
@@ −1 +1 @@
11 ---
22 glob: "**/*.ts"
3−description: "Langgraph Subgraphs & Workflow Orchestration"
3+description: "Langgraph Development Guidelines"
44 ---
5−# Subgraphs and Workflow Orchestration
65
7−## LangGraph Core Concept
6+# Development Guidelines
87
9−* This project heavily utilizes LangGraph's `StateGraph` to define and manage complex, multi-step AI agent workflows.
10−* A "graph" represents the flow of control and data between different nodes (which are typically agents or tool calls).
11−* Subgraphs allow you to reuse an existing graph as a node within another graph, promoting modularity and hierarchical organization.
8+## Coding Standards
129
13−## Key Components
10+* **Language:** TypeScript. Adhere to strict type-checking and leverage TypeScript's features for robust code.
11+* **Formatting:** Use Prettier (`prettier`) for consistent code formatting across the project. Ensure consistent indentation (likely 2 spaces), line endings, and brace style as configured in `eslint.config.ts`.
12+* **Linting:** Follow ESLint (`eslint`) rules defined in `eslint.config.ts`. Address all linting warnings and errors before committing code. Use `npm run lint` and `npm run format:check`.
13+* **Naming Conventions:** Adhere to conventional naming (camelCase for variables/functions, PascalCase for classes/interfaces) as enforced by ESLint.
14+* **Modularity:** Keep functions, modules, and especially agent nodes, small and focused on a single responsibility. This promotes reusability and easier debugging.
1415
15−* **Nodes:** Represent individual steps or agents in the workflow (e.g., `entryNode`, `supervisor`, `reactAgent`, `research_collectNode`). Each node takes the current `AgentState` as input and returns an updated state.
16−* **Edges:** Define the transitions between nodes.
17− * **Normal Edges:** Unconditionally move from one node to another (e.g., `START` to `entry`, `chat` to `END`).
18− * **Conditional Edges:** Route to different nodes based on a decision function (e.g., `routeMessages` from `supervisor` to various agents). The routing function takes the `AgentState` and returns the name of the next node(s) or `END`.
19−* **`AgentState`:** The central data structure that is passed and modified across all nodes in the graph, maintaining the conversation context and agent-specific data. Defined using `Annotation`.
20−* **Supervisor:** A critical node responsible for intelligently routing the `AgentState` to the appropriate specialized agent or action based on the current context and goal.
21−* **`Command` Primitive:** Allows combining state updates and control flow (routing) within a single node, useful for dynamic handoffs between agents.
16+## Best Practices
2217
23−## Designing Subgraphs
18+* **Error Handling:** Implement robust error handling, particularly for external tool calls and API interactions. Utilize custom error classes (e.g., `ToolExecutionError`, `ModelInvocationError`) and centralized error handling (e.g., `handleGlobalError` in `src/config/errors.ts`).
19+* **Logging:** Utilize the `winston` logger (`src/config/logger.ts`) for consistent and informative logging across the application. Use appropriate log levels (`debug`, `info`, `error`) for different environments.
20+* **Asynchronous Operations:** Use `async/await` for all asynchronous operations to maintain readability and manage control flow effectively.
21+* **Configuration Management:** Manage sensitive information and API keys using environment variables (e.g., `MONGODB_ATLAS_URI`, `GOOGLE_API_KEY`, `EXA_API_KEY`, `GITHUB_TOKEN`) via `.env` files for local development. Ensure proper environment variable setup (e.g., `process.env[name]`).
22+* **Tool Usage:** Ensure proper schema validation for tool inputs using `zod`. Design tools to be idempotent where possible.
23+* **Graph Design:** Follow LangGraph's principles: nodes do the work, edges define the flow. Use `StateGraph` for complex state management.
24+* **State Management:** Pay close attention to how state is passed and modified between nodes, leveraging `Annotation` and reducer functions for clear, predictable updates.
25+* **Dependency Management:** Manage dependencies using `npm` and ensure `@langchain/core` is resolved to a single version to prevent conflicts.
2426
25−* **Modularity:** Complex workflows should be broken down into smaller, manageable subgraphs or sequences of nodes.
26−* **Clear Responsibilities:** Each node and subgraph should have a clear, single responsibility.
27−* **State Flow:** Pay close attention to how data flows through the `AgentState` between nodes to ensure necessary information is available at each step.
28−* **Error Handling:** Design subgraphs to handle errors gracefully, potentially returning control to a supervisor for re-routing or error reporting.
29−* **Routing Logic:** The `routeMessages` function (or similar conditional routing) is crucial for dynamic and intelligent workflow execution. Ensure its logic covers all necessary transitions and fallback scenarios.
30−* **Communication:**
31− * If the parent graph and subgraph share schema keys (channels), the compiled subgraph can be added directly as a node.
32− * If schemas are different, define a node function that explicitly invokes the subgraph, transforming input state and output results to match the parent's schema. This prevents errors due to non-overlapping channels.
33−* **Nesting:** Subgraphs can be nested to any level, allowing for highly complex hierarchical agent systems.
27+## Tooling and Environment
3428
35−## Example Flows
29+* **IDE:** VS Code is the recommended development environment.
30+* **Package Manager:** npm.
31+* **Testing Framework:** Jest (`jest`) for unit and integration tests.
32+* **Build System:** TypeScript compiler (`tsc`) for transpilation (`npm run build`).
33+* **Version Control:** Git. Follow a clear branching strategy (e.g., `main` for stable code, feature branches for new development).
34+* **LangSmith:** Integrate LangSmith for best-in-class observability, debugging, testing, and monitoring of LLM applications. Set `LANGSMITH_API_KEY`, `LANGCHAIN_TRACING_V2`, and `LANGCHAIN_CALLBACKS_BACKGROUND` environment variables.
3635
37−* **General Conversation:** `entry` -> `supervisor` -> `chat` -> `END`
38−* **Research Task:** `entry` -> `supervisor` -> `research_collect` -> `research_summarize` -> `research_report` -> `supervisor` (for final response)
39−* **Documentation Task:** `entry` -> `supervisor` -> `draft_documentation` -> `finalize_documentation` -> `supervisor` (for final response)
40−* **React Agent Task:** `entry` -> `supervisor` -> `react` -> `supervisor` (for tool execution or further action)
41−* **Multi-agent Network:** Agents can communicate with each other in a many-to-many fashion, making decisions on which agent to call next (e.g., `travel_advisor` -> `sightseeing_advisor` -> `hotel_advisor`).
36+## Collaboration and Workflow
4237
43−## Persistence with Subgraphs
38+* **Version Control:** Utilize Git for all code changes. Adhere to a branching model that supports collaborative development and code reviews.
39+* **Code Reviews:** All significant code changes must undergo a thorough code review process to ensure quality, adherence to standards, and identification of potential issues.
40+* **Task Management:** Consider using a `cline_todo.md` file (as suggested in `.clinerules` best practices) to track tasks and subtasks within the project, ensuring clear summaries, timestamps, and status updates.
4441
45−* Checkpointers should be passed only when compiling the *parent* graph. LangGraph automatically propagates the checkpointer to child subgraphs, enabling persistence across nested levels.
46−* State of subgraphs can be viewed and updated, facilitating human-in-the-loop interactions and debugging within nested workflows.
42+## Testing Philosophy
43+
44+* **Unit Tests:** Write comprehensive unit tests for individual functions, modules, and especially for agent logic and tool implementations.
45+* **Integration Tests:** Develop integration tests to verify the interactions between different agents and external services within the LangGraph workflow.
46+* **Test Commands:** Use `npm run test` for unit tests, `npm run test:int` for integration tests, and `npm run test:all` for running all tests and linting checks.
47+* **Test-Driven Development (TDD):** Encourage a TDD approach where tests are written before the corresponding code to guide development and ensure testability.
4748
