GlassBox Code Repair Demo (powered by Lár)

This repository is a "killer demo" for the Lár Engine — an open-source, "glass box" framework for building auditable, multi-agent AI systems.

This demo showcases a Self-Correction Loop. It's not a chatbot; it's an autonomous engineer that fixes broken code.

You will see the agent:

1. Read broken Python code.
2. Run unit tests (which fail).
3. Debug the failure using an LLM.
4. Patch the code.
5. Loop until the tests pass.

The Lár Philosophy: Why a "Dumb" Engine Makes "Smart" Agents

The "magic" of AI agents isn't magic at all—it's just a graph. Other frameworks try to sell you a "magic" AgentExecutor that does everything at once. It's a "black box," and when it breaks, it's impossible to fix.

Lár is the opposite. It's a simple, "dumb" GraphExecutor loop. It runs one node, stops, and logs what happened.

This is the "glass box" advantage: the "intelligence" doesn't live in the engine; it lives in your nodes. This makes your agents 100% auditable and deterministic.

How it Works: The "Test-Debug-Patch" Loop

This agent uses a Cyclic Graph. It doesn't just go A -> B -> C. It goes A -> B -> C -> A until success.

1. Tester (ToolNode): Runs pytest. If it passes, we exit. If it fails, we continue.
2. Router (RouterNode): Checks the test result. PASS -> Success Node. FAIL -> Debugger Node.
3. Debugger (LLMNode): Reads the failure log and the source code. Generates a fix.
4. Patcher (ToolNode): Writes the fix to disk.
5. Loop: The graph points back to Tester.

Glass Box vs Black Box

Other Frameworks (“Black Box”)	Lár (“Glass Box”)
"Hidden Loops". You hope the agent decides to retry.	"Explicit Loops". You define the next_node pointing back to start.
"Magic" Output. The agent simply says "I fixed it".	"Auditable Proof". The GraphState shows every failed test, every patch, and every retry.
Flaky. Tends to get stuck in loops without exit conditions.	Controlled. You can insert RouterNodes to break loops after N retries.

How to Run This Demo

This demo includes a broken math library (src/math_lib.py) and a test suite (tests/test_math_lib.py).

1. repair_agent.py — Defines the graph logic.
2. run_demo.py — Runs the agent and prints the loop.

---

Prerequisites

• Python 3.11+
• Poetry
• Google Gemini API Key (or OpenAI)
• macOS/Linux/WSL/Windows

---

1 Installation

git clone https://github.com/snath-ai/code-repair-demo.git
cd code-repair-demo
# Install dependencies
poetry install

---

2 Set Up Environment Variables

Create a .env file:

GOOGLE_API_KEY="YOUR_API_KEY_HERE"

---

3 Run the Agent

poetry run python run_demo.py

You will see output like this:

[Step 1] Node: ToolNode (Tester)
  Test Result: FAIL

[Step 2] Node: RouterNode
  Routing to Debugger...

[Step 3] Node: LLMNode (Debugger)
  Agent is rewriting the code...

[Step 4] Node: ToolNode (Patcher)
  Patch applied.

[Step 5] Node: ToolNode (Tester)
  Test Result: PASS

---

How the Agent Works: Execution Blueprint

graph TD
    A[Start] --> B(ToolNode<br/>'Read Code');
    B --> C(ToolNode<br/>'Run Tests');
    C --> D{RouterNode<br/>'Pass or Fail?'};
    
    D -- "PASS" --> E[AddValueNode<br/>'Success'];
    D -- "FAIL" --> F(LLMNode<br/>'Debugger');
    
    F --> G(ToolNode<br/>'Patcher');
    G --> H(ClearErrorNode<br/>'Janitor');
    
    H -.-> C

Loading

Ready to Build a Real Agent?

We have built three "killer demos" that prove this "glass box" model. You can clone, build, and run them today.

• snath-ai/customer-support-demo: A Multi-Agent Swarm (Triage, Tech, Billing) on an assembly line.
• snath-ai/rag-demo: A Self-Correcting Research Agent using local vectors.
• snath-ai/code-repair-demo: (This Repo) A Self-Healing CI/CD Agent.

---

⚡ Ready to build with Lár? (Agentic IDEs)

Lár is designed for Agentic IDEs (Cursor, Windsurf, Antigravity) and strict code generation.

We provide a 3-Step Workflow to make your IDE an expert Lár Architect.

1. The Strategy: "Reference, Don't Copy"

Instead of pasting massive prompts, simply reference the master files in the lar/ directory (or download them from the main repo).

2. The Workflow

1. Context (The Brain): In your IDE chat, reference @lar/IDE_MASTER_PROMPT.md. This loads the strict typing rules and "Code-as-Graph" philosophy.
2. Integrations (The Hands): Reference @lar/IDE_INTEGRATION_PROMPT.md to generate production-ready API wrappers in seconds.
3. Scaffold (The Ask): Open @lar/IDE_PROMPT_TEMPLATE.md, fill in your agent's goal, and ask the IDE to "Implement this."

Example Prompt to Cursor/Windsurf: "Using the rules in @lar/IDE_MASTER_PROMPT.md, implement the agent described in @lar/IDE_PROMPT_TEMPLATE.md."

---

Support the Project

Lár is an open-source agent framework built to be clear, debuggable, and developer-friendly. If this project helps you, consider supporting its development through GitHub Sponsors.

Become a sponsor → Sponsor on GitHub

Credits

• Lár Engine by Aadithya Vishnu Sajeev — glass-box agent framework

License

This Project is licensed under the Apache License 2.0

This means:

• You are free to use Làr in personal, academic, or commercial projects.
• You may modify and distribute the code.
• You MUST retain the LICENSE and the NOTICE file.
• If you distribute a modified version, you must document what you changed.

Apache 2.0 protects the original author (Aadithya Vishnu Sajeev) while encouraging broad adoption and community collaboration.

For developers building on Làr: Please ensure that the LICENSE and NOTICE files remain intact to preserve full legal compatibility with the Apache 2.0 terms.