picogent-py/README.md

# PicoGent - Minimal AI Coding Agent

A lightweight AI coding assistant built in Python with minimal dependencies. PicoGent implements a ReAct (Reasoning and Acting) loop that allows LLMs to use tools to accomplish complex tasks.

## Features

- **Minimal Dependencies**: Only requires `httpx` - no heavy SDKs
- **ReAct Loop**: Classic reasoning and acting pattern for tool use
- **Anthropic Claude Support**: Direct API integration without SDK
- **Built-in Tools**: File operations (read/write/edit) and shell execution
- **Session Management**: JSONL-based conversation history
- **Skills System**: Extensible skills directory for custom prompts
- **Configurable**: JSON-based configuration with environment variable support

## Installation

```bash
# Clone the repository
git clone https://git.uix.su/markov/picogent-py.git
cd picogent-py

# Install dependencies
pip install -r requirements.txt

# Or install as a package
pip install -e .
```

## Quick Start

1. **Set up your API key**:
   ```bash
   export ANTHROPIC_API_KEY="your-api-key-here"
   ```

2. **Create a configuration file**:
   ```bash
   cp config.example.json config.json
   ```

3. **Use the agent**:
   ```python
   import asyncio
   from picogent import run_agent, Config

   async def main():
       # Load configuration
       config = Config.from_file("config.json")
       
       # Run agent with prompt
       response = await run_agent("List all files in the current directory", config)
       print(response)

   asyncio.run(main())
   ```

   Or use the CLI:
   ```bash
   python -m picogent.cli "Create a hello world Python script"
   ```

## Architecture

### Core Components

- **Agent** (`agent.py`): Main ReAct loop implementation
- **Provider** (`providers/anthropic.py`): Anthropic API integration using httpx
- **Tools** (`tools/`): Built-in tools for file and system operations
- **Session** (`session.py`): JSONL-based conversation history
- **Config** (`config.py`): Configuration management

### Built-in Tools

- **read**: Read file contents with optional offset/limit
- **write**: Write files with automatic directory creation
- **edit**: Find and replace text in files
- **bash**: Execute shell commands with timeout

### ReAct Loop

1. Build context (system prompt + history + user message)
2. Send to LLM with tool definitions
3. If no tool calls → return text response (done)
4. If tool calls → execute each tool, add results to history
5. Repeat from step 2 (max 20 iterations)

## Configuration

The `config.json` file supports:

```json
{
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "api_key": "env:ANTHROPIC_API_KEY",
  "max_tokens": 8192,
  "max_iterations": 20,
  "workspace": ".",
  "system_prompt": "You are a helpful coding assistant."
}
```

- `api_key` can reference environment variables with `env:VARIABLE_NAME`
- `workspace` sets the working directory for file operations
- `max_iterations` prevents infinite loops in the ReAct cycle

## Skills System

Add custom prompts and context to the `skills/` directory:

```
skills/
├── python-expert.md      # Python-specific knowledge
├── web-dev.md           # Web development skills
└── debugging.md         # Debugging techniques
```

Skills are automatically loaded and added to the system prompt.

## Session Management

Sessions are stored in JSONL format for easy inspection and debugging:

```python
# Save conversation to file
response = await agent.run("Create a Python script", session_file="conversation.jsonl")

# Load existing session
agent.session.load("conversation.jsonl")
```

## API Integration

The Anthropic provider uses direct HTTP requests with `httpx`:
- No official SDK dependency
- Full control over API calls
- Support for tool use and tool result messages
- Proper error handling and timeouts

## Development

The codebase follows these principles:
- **Minimal dependencies**: Only essential packages
- **Type hints**: Full type annotations
- **Async/await**: Modern Python async patterns
- **Error handling**: Comprehensive exception management
- **Extensibility**: Easy to add new tools and providers

## License

MIT License - see LICENSE file for details.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

## Roadmap

- [ ] OpenAI provider support
- [ ] Streaming responses
- [ ] Plugin system for custom tools
- [ ] Web interface
- [ ] Multi-agent coordination