Metadata-Version: 2.4
Name: agenai
Version: 0.1.0
Summary: A modular, extensible AI agent system
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.40.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.12.0
Provides-Extra: all
Requires-Dist: fastapi>=0.109.0; extra == 'all'
Requires-Dist: openai>=1.0.0; extra == 'all'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'all'
Requires-Dist: pytest>=8.0.0; extra == 'all'
Requires-Dist: ruff>=0.4.0; extra == 'all'
Requires-Dist: uvicorn[standard]>=0.27.0; extra == 'all'
Requires-Dist: websockets>=12.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Provides-Extra: server
Requires-Dist: fastapi>=0.109.0; extra == 'server'
Requires-Dist: uvicorn[standard]>=0.27.0; extra == 'server'
Requires-Dist: websockets>=12.0; extra == 'server'
Description-Content-Type: text/markdown

# Agenai

A modular, extensible AI agent system built around a core loop of **perceive -> reason -> act**.

## Features

- **Modular Architecture**: Build specialized agents with custom tools
- **Multiple LLM Providers**: Anthropic Claude, Ollama (local, free)
- **Web Interface**: FastAPI backend with WebSocket chat
- **Built-in Agents**: Teaching Assistant for teaching Python programming
- **Hooks System**: Full observability into agent behavior

## Installation

```bash
# Basic installation
pip install -e .

# With web server support (for chat UI)
pip install -e ".[server]"

# All dependencies
pip install -e ".[all]"
```

## Quick Start

### Option 1: Using Ollama (Free, Local)

No API key required! Uses local LLMs.

```bash
# 1. Install Ollama from https://ollama.ai

# 2. Pull a model
ollama pull llama3.1

# 3. Start the web server
agenai-server

# 4. Open http://localhost:8000 in your browser
```

### Option 2: Using Claude API

```bash
# Set your API key
export ANTHROPIC_API_KEY="your-key"

# Run CLI
agenai run "Explain Python for loops" -v

# Or interactive chat
agenai chat
```

## Web Chat Interface

Start the server with WebSocket support:

```bash
# Install server dependencies
pip install -e ".[server]"

# Start server
agenai-server --port 8000

# Or with auto-reload for development
agenai-server --reload
```

Open http://localhost:8000 for the chat UI.

## API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/` | GET | Web chat interface |
| `/health` | GET | Health check + Ollama status |
| `/chat` | POST | REST chat endpoint |
| `/ws/{client_id}` | WebSocket | Real-time chat |

## Creating Custom Agents

```python
from agenai.agent import SpecializedAgent, OllamaProvider
from agenai.agent.tools import Tool, ToolResult

class MyTool(Tool):
    @property
    def name(self) -> str:
        return "my_tool"

    @property
    def description(self) -> str:
        return "Does something useful"

    @property
    def parameters(self) -> dict:
        return {"type": "object", "properties": {}}

    def execute(self) -> ToolResult:
        return ToolResult.ok("Done!")

class MyAgent(SpecializedAgent):
    name = "my_agent"
    description = "My custom agent"

    def get_system_prompt(self) -> str:
        return "You are a helpful assistant..."

    def get_tools(self) -> list:
        return [MyTool()]

# Use with Ollama (free, local)
agent = MyAgent(llm=OllamaProvider(model="llama3.1"))
result = agent.run("Hello!")
```

## Built-in Agents

### Teaching Assistant

Teaching assistant for Python programming:

```python
from agenai.agents.teaching_assistant import TeachingAssistantAgent

agent = TeachingAssistantAgent(difficulty_level="beginner")
result = agent.run("Explain what a for loop is")
```

Tools: `run_code`, `review_code`, `create_exercise`, `create_quiz`

## Architecture

```
┌─────────────┐     WebSocket      ┌─────────────┐              ┌─────────────┐
│   Frontend  │ <================> │   Backend   │ <==========> │   Ollama    │
│  (Web Chat) │                    │  (FastAPI)  │              │ (Local LLM) │
└─────────────┘                    └──────┬──────┘              └─────────────┘
                                          │
                                          ▼
                                   ┌─────────────┐
                                   │   Agenai    │
                                   │   Agents    │
                                   └─────────────┘
```

See `AI-AGENT-ARCHITECTURE.md` for full details.

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Format code
ruff check --fix .
```

## Publishing to PyPI

### Local Publishing

```bash
# Build only
./scripts/publish.sh --build-only

# Publish to TestPyPI
TEST_PYPI_TOKEN=xxx ./scripts/publish.sh --test

# Publish to PyPI
PYPI_TOKEN=xxx ./scripts/publish.sh
```

### Automated Publishing (GitHub Actions)

The repo includes a GitHub Actions workflow that auto-publishes to PyPI on release.

**Setup Trusted Publisher on PyPI:**

1. Go to https://pypi.org/manage/account/publishing/
2. Click "Add a new pending publisher"
3. Fill in:
   - **PyPI Project Name**: `agenai`
   - **Owner**: `tautobot`
   - **Repository**: `agenai`
   - **Workflow name**: `publish.yml`
   - **Environment name**: `pypi`

**Setup Trusted Publisher on TestPyPI:**

1. Go to https://test.pypi.org/manage/account/publishing/
2. Same fields as above, but **Environment name**: `testpypi`

**Setup GitHub Environments:**

1. Go to https://github.com/tautobot/agenai/settings/environments
2. Create environment `pypi`
3. Create environment `testpypi`
4. (Optional) Add protection rules like required reviewers

Once configured, the GitHub Action publishes without API tokens using OIDC.

## License

MIT
