README.md

metadata

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

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

pip install -r requirements.txt
python main.py

Docker

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

docker compose up --build

Run tests (no API keys needed)

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