🏦 Karbon AI Challenge – Bank Statement Parser Agent

This repository contains my solution for the Karbon AI Challenge.
The agent automatically generates a parser for bank statements (ICICI bank in this case), validates it against expected outputs, and ensures the parser meets all requirements.

---

🚀 Features

• Automatic parser generation using Gemini (if API key available)

• Fallback parser ensures robustness even without LLM

• Enforces strict parser contract:

  def parse(pdf_path: str) -> pd.DataFrame

• Schema enforced:

  ["Date", "Description", "Debit Amt", "Credit Amt", "Balance"]
  

• Self-correcting loop with up to 3 attempts

• Comprehensive test suite included

---

📂 Project Structure

├── agent.py                  # Main agent script
├── test_parser.py            # Test suite for generated parsers
├── custom_parsers/           # Generated parsers saved here
│   └── icici_parser.py
├── data/
│   └── icici/
│       ├── icici_sample.pdf  # Sample bank statement (PDF)
│       └── icici_sample.csv  # Expected parsed output
├── requirements.txt
├── .env.example              # Example environment variables
├── .gitignore
└── README.md

---

⚙️ Setup

1. Clone the repo

   git clone https://github.com/thammi21/karbon-ai-challenge.git
   cd karbon-ai-challenge

2. Create virtual environment

   python -m venv venv
   source venv/bin/activate    # Linux/Mac
   venv\Scripts\activate       # Windows

3. Install dependencies

   pip install -r requirements.txt

4. Set API keys
   Copy .env.example → .env and add your real key:

   GOOGLE_API_KEY=your_api_key_here

5. Run the agent

   python agent.py --target icici

---

📊 Agent Flow Diagram

flowchart TD
    A(["Start: Run agent.py"]) --> B(["Analyze requirements\n(expected schema & PDF sample)"])
    B --> C(["Generate parser code\nvia Gemini or fallback"])
    C --> D{Test parser\nvs CSV ground truth?}
    D -->|Pass| E(["✅ Success: Parser saved\nAll tests passed"])
    D -->|Fail| F(["Self-correct with error context"])
    F --> C
    F -->|Max attempts reached| G(["❌ Failure: Report error"])

Loading

Agent Diagram Explanation:
The agent begins by running agent.py and analyzing the expected schema along with the PDF sample. It generates parser code using Gemini if available, or a fallback method. The generated parser is tested against the CSV ground truth; if it passes, it is saved and marked as successful. If the test fails, the agent enters a self-correcting loop to fix errors and retry parser generation. After reaching the maximum attempts without success, the agent reports a failure.

---

▶️ Running the Agent

python agent.py --target icici

Expected output:

✅ Gemini client initialized
🚀 Starting agent for ICICI bank parser generation...
📋 Expected schema: ['Date', 'Description', 'Debit Amt', 'Credit Amt', 'Balance']
📏 Expected shape: (100, 5)
💾 Parser written to custom_parsers/icici_parser.py
✅ Parser test passed!
🎉 SUCCESS! Parser available at custom_parsers/icici_parser.py

---

🧪 Testing the Parser

python test_parser.py

Expected:

🧪 Running Parser Tests
✅ Parser contract test PASSED!
📊 Shape comparison: result=(100, 5), expected=(100, 5)
🎉 ICICI parser test PASSED!
🎉 ALL TESTS PASSED!
✅ Agent challenge requirements met!

---

👨‍💻 Author

Mohammed Thameem
Solution for Karbon AI Challenge