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

# 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

pip install claia-template

Usage

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

Using the Demo Agent

# 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

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

2. Customize the Project

Update pyproject.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):

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

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 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

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
• CLAIA - The main CLAIA framework
• 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.