---
title: LangGraph Agent
emoji: 🐠
colorFrom: red
colorTo: purple
sdk: docker
pinned: false
---

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

# LangGraph Agent — Modular Structure

A production-ready LangGraph application with 8 agentic checkpoints,
modular architecture, and Docker support.

## Project Structure

```
langgraph_agent/
├── app/
│   ├── config.py              # All settings (env-driven)
│   ├── state.py               # AgentState TypedDict
│   ├── nodes/
│   │   ├── router.py          # ✅ Checkpoint 3 — Conditional routing
│   │   ├── rag.py             # ✅ Checkpoint 2 — RAG retrieval
│   │   ├── llm_node.py        # ✅ Checkpoint 4 — Retries
│   │   ├── tool_executor.py   # ✅ Checkpoint 1 — Tool execution
│   │   ├── memory.py          # ✅ Checkpoint 5 — Memory
│   │   ├── hitl.py            # ✅ Checkpoint 6 — Human-in-the-Loop
│   │   ├── evaluation.py      # ✅ Checkpoint 7 — Evaluation
│   │   ├── guardrails.py      # ✅ Checkpoint 8 — Guardrails
│   │   └── output.py          # Final output node
│   ├── tools/
│   │   ├── calculator.py      # Math expression tool
│   │   └── weather.py         # Weatherstack API tool
│   ├── rag/
│   │   └── store.py           # FAISS vector store + retrieval
│   ├── graph/
│   │   └── builder.py         # Graph topology assembly
│   └── utils/
│       └── llm.py             # LLM singleton factory
├── tests/
│   └── test_nodes.py          # Unit tests (no API key needed)
├── main.py                    # CLI entry point
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
└── .env.example
```

## Quickstart

### Local

```bash
cp .env.example .env
# Fill in GROQ_API_KEY and WEATHER_API_KEY

pip install -r requirements.txt
python main.py
```

### Docker

```bash
cp .env.example .env
# Fill in your API keys in .env

docker compose up --build
```

### Run tests (no API keys needed)

```bash
pip install pytest
pytest tests/
```

## Adding a new tool

1. Create `app/tools/my_tool.py` with a `@tool` function
2. Import it in `app/tools/__init__.py` and add to `ALL_TOOLS`
3. Done — the router and LLM binding pick it up automatically

## Environment Variables

| Variable         | Description                        | Default                     |
|------------------|------------------------------------|-----------------------------|
| GROQ_API_KEY     | Groq API key                       | required                    |
| WEATHER_API_KEY  | Weatherstack API key               | required for weather tool   |
| LLM_MODEL        | Groq model name                    | llama-3.3-70b-versatile     |
| LLM_TEMPERATURE  | LLM temperature                    | 0                           |
| MAX_RETRIES      | Max LLM retry attempts             | 3                           |
| EVAL_THRESHOLD   | Min quality score before retry     | 0.6                         |
| HITL_ENABLED     | Enable human approval gate         | true                        |