Skip to content

Commit 9139369

Browse files
dahlinominedahlinomine
committed
feat(adapter): add complete LangGraph export and run adapter
- src/adapters/langgraph.ts: full StateGraph export with SOUL.md/RULES.md/ skills/knowledge/compliance mapping, @tool stubs from tools/*.yaml, and HITL nodes for human_in_the_loop (always/conditional) - src/runners/langgraph.ts: runner that generates agent.py + isolated venv + pip install, executes via python agent.py [--prompt] - src/adapters/langgraph.test.ts: 20 node:test unit tests covering export structure, model routing (Claude/OpenAI/Gemini), HITL wiring, requirements - docs/adapters/langgraph.md: full field mapping, graph diagrams, model resolution table, compliance mapping, usage examples - src/adapters/index.ts: add exportToLangGraphString, exportToLangGraph - src/commands/export.ts: wire langgraph case + update format description - src/commands/run.ts: wire langgraph case + import runWithLangGraph
1 parent 618b46d commit 9139369

File tree

7 files changed

+1088
-11
lines changed

7 files changed

+1088
-11
lines changed

‎docs/adapters/langgraph.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# LangGraph Adapter
2+
3+
Complete mapping guide for converting between gitagent and LangGraph formats.
4+
5+
## Overview
6+
7+
[LangGraph](https://langchain-ai.github.io/langgraph/) is LangChain's graph-based agent orchestration framework for Python. It models agents as `StateGraph` objects where:
8+
9+
- **Nodes** are Python functions that receive and return state
10+
- **Edges** are routing decisions (conditional or fixed)
11+
- **State** is a typed dictionary (`TypedDict`) carrying messages between nodes
12+
- **Tools** are Python functions decorated with `@tool`
13+
14+
The gitagent LangGraph adapter enables:
15+
1. **Export**: Convert gitagent → LangGraph Python code (`agent.py`)
16+
2. **Run**: Execute gitagent agents using the generated Python agent
17+
18+
## Installation
19+
20+
```bash
21+
# LangGraph requires Python 3.11+
22+
pip install langgraph langchain-core
23+
24+
# Provider-specific:
25+
pip install langchain-openai # for GPT models
26+
pip install langchain-anthropic # for Claude models
27+
pip install langchain-google-genai # for Gemini models
28+
```
29+
30+
## Field Mapping
31+
32+
### Export: gitagent → LangGraph
33+
34+
| gitagent | LangGraph | Notes |
35+
|----------|-----------|-------|
36+
| `SOUL.md` | `SYSTEM_PROMPT` (identity section) | Embedded as Python string constant |
37+
| `RULES.md` | `SYSTEM_PROMPT` (constraints section) | Appended to system prompt |
38+
| `DUTIES.md` | `SYSTEM_PROMPT` (SOD section) | Appended to system prompt |
39+
| `skills/*/SKILL.md` | `SYSTEM_PROMPT` (skills section) | Progressive disclosure, full instructions |
40+
| `tools/*.yaml` | `@tool` decorated functions | Stub implementations — fill in logic |
41+
| `knowledge/` (always_load) | `SYSTEM_PROMPT` (knowledge section) | Reference documents embedded |
42+
| `manifest.model.preferred` | LLM constructor (`ChatOpenAI`, `ChatAnthropic`, `ChatGoogleGenerativeAI`) | Auto-detected from model name prefix |
43+
| `compliance.supervision.human_in_the_loop: always` | `human_review_node` (blocks on every tool call) | Inserted between `agent` and `tools` nodes |
44+
| `compliance.supervision.human_in_the_loop: conditional` | `human_review_node` (blocks on risky tools) | Heuristic based on tool name keywords |
45+
| `compliance.supervision.human_in_the_loop: none` | No HITL node | Fully autonomous |
46+
| `manifest.version` | Docstring | Recorded for traceability |
47+
48+
### Graph Structure
49+
50+
**Without HITL:**
51+
```
52+
START → agent → (should_continue) → tools → agent (loop)
53+
↓
54+
END
55+
```
56+
57+
**With HITL (`always` or `conditional`):**
58+
```
59+
START → agent → human_review → (should_continue) → tools → agent (loop)
60+
↓
61+
END
62+
```
63+
64+
## Model Resolution
65+
66+
| gitagent `model.preferred` | LangGraph import | Class |
67+
|----------------------------|------------------|-------|
68+
| `claude-*` or `anthropic/*` | `langchain_anthropic` | `ChatAnthropic` |
69+
| `gpt-*`, `o1*`, `o3*`, `openai/*` | `langchain_openai` | `ChatOpenAI` |
70+
| `gemini-*` or `google/*` | `langchain_google_genai` | `ChatGoogleGenerativeAI` |
71+
| *(other)* | `langchain_openai` | `ChatOpenAI` |
72+
73+
## Usage Examples
74+
75+
### Export to LangGraph
76+
77+
```bash
78+
# Export to stdout
79+
gitagent export --format langgraph -d ./my-agent
80+
81+
# Save to file
82+
gitagent export --format langgraph -d ./my-agent -o agent.py
83+
```
84+
85+
**Output Structure:**
86+
```
87+
# === agent.py ===
88+
"""LangGraph agent generated from gitagent manifest…"""
89+
from langchain_openai import ChatOpenAI
90+
from langgraph.graph import StateGraph, END
91+
…
92+
93+
# === requirements.txt ===
94+
langgraph>=0.2.0
95+
langchain-core>=0.3.0
96+
langchain-openai>=0.3.0
97+
python-dotenv>=1.0.0
98+
99+
# === .env.example ===
100+
OPENAI_API_KEY=your-openai-api-key
101+
```
102+
103+
### Run with LangGraph
104+
105+
```bash
106+
# Interactive mode
107+
gitagent run --adapter langgraph -d ./my-agent
108+
109+
# Single-shot mode
110+
gitagent run --adapter langgraph -d ./my-agent --prompt "Summarise the latest SEC filings"
111+
```
112+
113+
The runner:
114+
1. Generates `agent.py`, `requirements.txt`, and `.env.example` in a temp workspace
115+
2. Creates a Python virtual environment
116+
3. Installs dependencies via `pip install -r requirements.txt`
117+
4. Executes `python agent.py [--prompt "…"]`
118+
5. Cleans up the temp workspace on exit
119+
120+
### Running the generated agent directly
121+
122+
```bash
123+
# After export:
124+
cp .env.example .env && vim .env # add your API key
125+
pip install -r requirements.txt
126+
python agent.py # interactive REPL
127+
python agent.py --prompt "Hello" # single-shot
128+
```
129+
130+
## Compliance Mapping
131+
132+
| gitagent `human_in_the_loop` | LangGraph behaviour |
133+
|------------------------------|---------------------|
134+
| `always` | `human_review_node` inserted — user must type `y` to approve **every** tool call |
135+
| `conditional` | `human_review_node` inserted — approval required only for write/delete/send/post operations |
136+
| `advisory` | No HITL node — advisory note added in system prompt only |
137+
| `none` | No HITL node — fully autonomous |
138+
139+
## Implementing Tools
140+
141+
The adapter generates stub `@tool` functions from `tools/*.yaml`. You need to fill in the implementation:
142+
143+
```python
144+
# Before (generated stub)
145+
@tool
146+
def search_regulations(query: str) -> str:
147+
"""Search regulatory database."""
148+
raise NotImplementedError("Implement search_regulations tool")
149+
150+
# After (your implementation)
151+
@tool
152+
def search_regulations(query: str) -> str:
153+
"""Search regulatory database."""
154+
results = my_db.search(query)
155+
return "\n".join(r.text for r in results)
156+
```
157+
158+
## Generated File Reference
159+
160+
### `agent.py`
161+
162+
| Section | Description |
163+
|---------|-------------|
164+
| `SYSTEM_PROMPT` | Full agent identity + rules + skills as string constant |
165+
| `TOOLS` | List of `@tool`-decorated functions (stubs from `tools/*.yaml`) |
166+
| `AgentState` | `TypedDict` with `messages: Annotated[list[BaseMessage], add_messages]` |
167+
| `agent_node` | Calls LLM with tools bound; prepends system prompt |
168+
| `should_continue` | Routes to `"tools"` if last message has tool calls, else `END` |
169+
| `human_review_node` | (HITL only) Prompts user for approval before tool execution |
170+
| `build_graph` | Wires nodes and edges into a compiled `StateGraph` |
171+
| `main` | CLI entry point: `--prompt` for single-shot, interactive REPL otherwise |
172+
173+
### `requirements.txt`
174+
175+
Minimal set of pip packages needed to run the agent.
176+
177+
### `.env.example`
178+
179+
Template for environment variables (API keys). Copy to `.env` and fill in.
180+
181+
## Notes
182+
183+
- Tools are generated as **stubs** — the adapter cannot infer implementation from YAML declarations alone. Fill in the function body before use.
184+
- The runner requires **Python 3.11+** and **pip** on PATH.
185+
- For production use, replace the `tmpdir`-based approach with a persistent project directory.
186+
- LangGraph does not natively support gitagent's agent versioning or branch deployment patterns — those remain in the git layer.

‎src/adapters/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,4 @@ export { exportToOpenCodeString, exportToOpenCode } from './opencode.js';
99
export { exportToCursorString, exportToCursor } from './cursor.js';
1010
export { exportToGeminiString, exportToGemini } from './gemini.js';
1111
export { exportToCodexString, exportToCodex } from './codex.js';
12+
export { exportToLangGraphString, exportToLangGraph } from './langgraph.js';

0 commit comments

Comments
 (0)