codantic-ai

# Codantic AI - Educational AI Agent Loop

> **For Educational Purposes Only** - Learn AI agent architecture with minimal abstractions

A Python AI agent system using **Pydantic AI's Direct API** for maximum learning clarity. Built with Google Gemini and featuring 9 file system tools.

## 🧠 **Why This Approach?**

Uses `pydantic_ai.direct.model_request_sync()` - minimal abstraction perfect for learning:
- **🔍 See exactly** how LLM interactions work
- **📚 No magic** - every API call is explicit  
- **🛠 Direct control** over context and tool calling

## 🎬 **Live Demo**

![Demo](demo.gif)

## 🛠 **9 Built-in Tools**

| Tool | Description |
|------|-------------|
| `read` | Read files with optional line limits |
| `write` | Create files with audit logging |
| `edit` | String replacements in files |
| `multiedit` | Multiple edits atomically |
| `ls` | List directory contents |
| `glob` | Pattern-based file search |
| `grep` | Regex search in file contents |
| `bash` | Execute shell commands |
| `todo` | Task management |

## 🚀 **Quick Start**

### Prerequisites
- Python 3.13+
- Google Claude API key ([Get one here](https://ai.google.dev/))

### Installation
```bash
git clone <your-repo-url>
cd codantic-ai

# Setup environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install dependencies  
pip install -r requirements.txt
# OR: uv sync

# Configure API key
cp .env.example .env
# Edit .env and add your Claude API key

# Run the agent
python main.py
```

## 🏗 **How It Works**

```mermaid
graph TB
    A[👤 User Input] --> B[🔄 AgentLoop]
    B --> C[🤖 Pydantic AI Direct API]
    C --> D{🛠 Tool Calls?}
    D -->|Yes| E[⚡ Execute Tools]
    E --> B
    D -->|No| F[💬 Response]
```

### Key Learning Points
```python
# Direct API usage - no hidden abstractions!
model_response = model_request_sync(
    self.model_name,
    self.context,  # Full conversation history
    model_request_parameters=ModelRequestParameters(
        fun