Show HN: Open-source reference architecture for AI Agents (LangGraph, Pydantic)

Hi HN,

I wanted to share a reference implementation I architected for moving AI Agents from local prototypes to production services.

The Context:

It is relatively easy to get an agent working on a local machine where you can watch the terminal output and restart it if it gets stuck. However, the architecture often breaks down when moving to a headless, hosted environment where the agent needs to handle loops, persistent state, and structured output failures autonomously.

The Solution:

This repo is a 10-lesson lab where you build an "AI Codebase Analyst" designed to handle those operational constraints.

Key Architectural Decisions:

1) State Management (LangGraph): We use LangGraph to implement the State Machine pattern rather than a linear Chain. This provides a standardized way to handle cyclic logic (loops) and persistence without writing "spaghetti code" while loops.

2) Reliability (Pydantic): Treating the LLM as a probabilistic component. We wrap tool calls in strict Pydantic schemas to catch and retry malformed JSON before it hits the application logic.

3) Deployment (Docker): A production-ready Dockerfile setup for serverless environments.

The Repo Structure:

starter branch: A clean boilerplate to build from scratch.

main branch: The full solution code.

curriculum/ folder: The step-by-step guide.

Happy to answer questions about the stack or the trade-offs involved.