# jrats/karbon-ai-agent-challenge architecture

> Architecture diagram of the GitHub repository jrats/karbon-ai-agent-challenge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jrats/karbon-ai-agent-challenge
- Repository: https://github.com/jrats/karbon-ai-agent-challenge

## Overview

##### Project Type & Purpose
- This is an automation/orchestration tool (an “agent”) built around a LangGraph pipeline.
- Its goal: generate, execute, test, and iteratively fix custom Python parsers for bank statement PDFs by leveraging an LLM.

##### Pinpoint the Main Components
a. Input Data Layer
– “data/<bank>/” directory containing PDF (e.g., icici sample.pdf) and ground-truth CSV (result.csv).
b. Orchestrator (agent.py + LangGraph)
– Core Python script that defines and wires together four nodes.
c. Nodes in the Workflow
1. CodeGen
- Calls OpenAI API with prompts (prompts.py) to generate parser code.
2. Executor
- Writes the code to a .py file in working directory.
3. Tester
- Runs pytest (tests/test_icici_parser.py) against the newly generated parser, comparing output to CSV.
4. Fixer
- On test failures, sends logs back to the LLM for repair suggestions.
d. Cache & Storage
– “cache/<bank>/success.py” for successful parser code.
– “custom_parsers/<bank>_parser.py” as final output.
– Local filesystem for intermediate logs.
e. External Services & Libraries
– OpenAI API (LLM)
– pdfplumber (PDF → text extraction)
– pandas (table processing)
– pytest (automated testing)

##### Relationships & Data Flows
- Data flow is cyclical:
1. Input PDF & CSV → CodeGen → generated parser code.
2. Parser code → Executor → file on disk.
3. Parser file + PDF → Tester → test result (pass/fail + diagnostics).
4. On fail → Fixer → updated code suggestions → back to Executor.
- On success, branch out: cache code and dump final parser.
- All calls to the LLM go through an API boundary.

##### Architectural Patterns & Design Principles
- Pipeline/orchestration pattern (LangGraph nodes wired in sequence with a loop back on failures).
- Separation of concerns: code generation, execution, testing, fixing.
- Caching layer to avoid redundant LLM calls.
- Plugin-style extensibility: each bank’s parser is isolated under its own folder.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Services"
        OpenAI["OpenAI API"]:::external
    end

    subgraph "Input Data"
        DataPDF["icici sample.pdf"]:::data
        DataCSV["result.csv"]:::data
    end

    subgraph "Orchestrator"
        Orchestrator["LangGraph Pipeline (agent.py)"]:::bluenode
    end

    subgraph "Workflow Nodes"
        CodeGen["CodeGen"]:::bluenode
        Executor["Executor"]:::bluenode
        Tester["Tester"]:::bluenode
        Fixer["Fixer"]:::bluenode
    end

    subgraph "Libraries"
        ParserLibs["pdfplumber & pandas"]:::lib
        Pytest["pytest"]:::lib
    end

    subgraph "Cache & Output"
        CacheStorage["cache/icici/success.py"]:::data
        FinalParser["custom_parsers/icici_parser.py"]:::data
    end

    %% Data to CodeGen
    DataPDF -->|PDF input| CodeGen
    DataCSV -->|Schema CSV| CodeGen

    %% Orchestration
    Orchestrator -->|Start pipeline| CodeGen

    %% OpenAI integration
    CodeGen -->|Generate prompt| OpenAI
    OpenAI -->|Return generated code| CodeGen
    Fixer -->|Fix request| OpenAI
    OpenAI -->|Return fixes| Fixer

    %% Workflow flow
    CodeGen -->|Generated parser code| Executor
    Executor -->|Write .py to disk| ParserLibs
    ParserLibs -->|Used by parser| Executor
    Executor -->|Execute parser + PDF| Tester
    Tester -->|Run tests| Pytest
    Pytest -->|Results| Tester

    %% Success path
    Tester -->|Tests pass| CacheStorage
    CacheStorage -->|Save final parser| FinalParser

    %% Failure loop
    Tester -->|Tests fail| Fixer
    Fixer -->|Updated code| Executor

    %% Click events
    click DataPDF "https://github.com/jrats/karbon-ai-agent-challenge/blob/main/data/icici/icici sample.pdf"
    click DataCSV "https://github.com/jrats/karbon-ai-agent-challenge/blob/main/data/icici/result.csv"
    click Orchestrator "https://github.com/jrats/karbon-ai-agent-challenge/blob/main/agent.py"
    click CodeGen "https://github.com/jrats/karbon-ai-agent-challenge/blob/main/prompts.py"
    click Executor "https://github.com/jrats/karbon-ai-agent-challenge/blob/main/agent.py"
    click Tester "https://github.com/jrats/karbon-ai-agent-challenge/blob/main/tests/test_icici_parser.py"
    click Fixer "https://github.com/jrats/karbon-ai-agent-challenge/blob/main/agent.py"

    %% Styles
    classDef bluenode fill:#D6EAF8,stroke:#3498DB,color:#000
    classDef data fill:#D5F5E3,stroke:#27AE60,color:#000
    classDef external fill:#FAD7A0,stroke:#D68910,color:#000
    classDef lib fill:#EBEBEB,stroke:#797D7F,color:#000
```
