# CLAIA Extension Template

A template and reference implementation for creating CLAIA extensions. This project demonstrates how to build custom agents, tools, and other plugins for the CLAIA framework.

- Website: https://claia.dev
- License: Apache-2.0
- Python: 3.12+

## Overview

This template provides a working example of a CLAIA extension with a simple demo agent. Use it as a starting point for creating your own CLAIA extensions, whether you're building custom agents, tools, architectures, or other plugin types.

## Installation

### From Source

```bash
# Clone the repository
git clone https://gitlab.com/exofox/claia/claia-template.git
cd claia-template

# Create virtual environment
python -m venv .venv
. .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -U pip
pip install -e .
```

### From PyPI

```bash
pip install claia-template
```

## Usage

After installation, the demo agent will be automatically registered in CLAIA.

### Using the Demo Agent

```bash
# Start CLAIA with the demo agent
claia --default-agent demo

# Or switch to it in interactive mode
:agent demo
```

## Creating Your Own Extension

### 1. Clone This Template

```bash
git clone https://gitlab.com/exofox/claia/claia-template.git my-extension
cd my-extension
```

### 2. Customize the Project

Update `pyproject.toml`:

```toml
[project]
name = "claia-my-extension"
description = "My custom CLAIA extension"
# ... update other metadata

[project.entry-points."claia.agents"]
my_agent = "my_module.agent:MyAgentPlugin"
```

### 3. Implement Your Plugin

Modify `src/claia_agent/agent.py` (or rename the module):

```python
import pluggy
from typing import Type
from claia.lib import BaseAgent, Process
from claia.hooks import AgentInfo

hookimpl = pluggy.HookimplMarker("claia_agents")

class MyAgent(BaseAgent):
    @classmethod
    def process_request(cls, process, registry=None, **kwargs):
        # Your custom agent logic here
        model_id = process.parameters["model_id"]
        result = registry.run(model_id, process.conversation, **kwargs)
        
        if result.is_error():
            process.mark_failed(result.get_message())
        else:
            process.mark_completed(result.data)
        
        return process

class MyAgentPlugin:
    @hookimpl
    def get_agent_class(self, agent_name: str) -> Type[BaseAgent]:
        if agent_name.lower() == "my_agent":
            return MyAgent
        return None
    
    @hookimpl
    def get_agent_info(self) -> AgentInfo:
        return AgentInfo(
            name="my_agent",
            description="My custom agent",
            agent_class=MyAgent
        )
```

### 4. Install and Test

```bash
pip install -e .
claia --default-agent my_agent
```

## Extension Types

CLAIA supports various extension types through different entry points:

- `claia.agents` - Custom agent implementations
- `claia.tool_modules` - Tool command modules
- `claia.architectures` - Model architecture adapters
- `claia.deployments` - Runtime backends
- `claia.solvers` - Model selection strategies
- `claia.definitions` - Model metadata and canonical IDs

Refer to the [CLAIA documentation](https://gitlab.com/exofox/claia/claia) for details on each type.

## Project Structure

```
claia-template/
├── src/
│   └── claia_agent/
│       ├── __main__.py
│       └── agent.py         # Demo agent implementation
├── pyproject.toml           # Project config & entry points
├── deploy.sh                # Deployment script
├── LICENSE
├── NOTICE
└── README.md
```

## Building and Distribution

### Build Wheel

```bash
pip install build
python -m build

# Or use the deploy script (will put whl under dist/whl/your-whl-file.whl)
./deploy --build-whl
```

This creates a wheel in `dist/` that can be:
- Uploaded to PyPI
- Installed directly with `pip install dist/*.whl`
- Distributed to users

### Deploy Script

The included `deploy.sh` script can help automate building and deployment.

## Related Projects

- [CLAIA's Website](https://claia.dev)
- [CLAIA](https://gitlab.com/exofox/claia/claia) - The main CLAIA framework
- [CLAIA Bob](https://gitlab.com/exofox/claia/claia-bob) - Bob tells it to you straight.

## Support

- Documentation: https://claia.dev
- Issues: https://gitlab.com/exofox/claia/claia-template/-/issues
- Main Project: https://gitlab.com/exofox/claia/claia

## License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
