chatixia-agent 0.1.0

Chatixia: a domain-agnostic skill-based AI agent framework

Chatixia

Chatixia is a skill-based AI assistant powered by Azure OpenAI. Its extensible skill system lets you perform document processing, image manipulation, database queries, workflow automation, and more through natural language.

Features

• Extensible skill system — Add custom capabilities via Python, JavaScript, or binary handlers
• Session management — Save and restore conversation history
• Long-term memory — Remember important facts across sessions
• Document processing — Analyze PDFs and images with Azure Document Intelligence
• Knowledge base — Ingest documents and web pages for agent-searchable context
• Workflow automation — Capture conversations as reusable multi-step workflows
• Integrations — Azure AI Search, PostgreSQL (read-only), and more
• MCP support — Connect external tool servers (Playwright, GitHub, etc.)
• Local deployment — Package and run agents anywhere with pip install chatixia

Quick Start (SDK)

pip install chatixia
chatixia init my-agent
# Edit agent.yaml and .env with your API keys
chatixia run

See the SDK documentation for the full guide.

Full Platform Setup

Prerequisites

• Python 3.14+
• uv package manager
• Node.js 20+ (for the Web UI)

Installation

git clone https://github.com/Chatixia-AI/chatixia-agent.git
cd chatixia-agent

uv sync

cp .env.example .env
# Edit .env with your API keys

Environment Variables

Add the following to .env:

# Azure OpenAI (required)
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_KEY=your-api-key
AZURE_OPENAI_DEPLOYMENT=gpt-5.2

# Azure Document Intelligence (for analyze_document skill)
AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT=https://your-resource.cognitiveservices.azure.com/
AZURE_DOCUMENT_INTELLIGENCE_KEY=your-api-key

Running

# CLI REPL
uv run cli/main.py

# Backend API (port 8000)
uv run uvicorn server.api:app --reload

# Web UI (port 5173)
cd web && npm install && npm run dev

# Debug logging
LOG_LEVEL=DEBUG uv run cli/main.py

CLI Commands

Command	Description
/new	Start a new session (auto-saves current)
/sessions	List saved sessions
/resume <id>	Resume a saved session
/delete <id>	Delete a session
/history	Show current session info
/export	Export session as JSON
/remember <text>	Save a fact to long-term memory
/memories	List saved memories
/forget <id>	Delete a memory
/help	Show help
quit, exit, q	Exit

Skills

Built-in Skills

Skill	Description
analyze_document	Analyze documents with Azure Doc Intelligence
pdf_to_images	Convert PDF pages to images
crop_image	Crop an image
get_image_size	Get image dimensions
summarizer	Summarize text
calculator	Evaluate math expressions
echo	Echo a message back
postgres_readonly_query	Query PostgreSQL (read-only)
get_ariba_data	Fetch data from SAP Ariba
azure_ai_search	Search Azure AI Search index
spawn_sub_agent	Delegate tasks to a sub-agent
render_ui	Generate rich UI components (charts, tables)
flow_chart_builder	Build flow chart visualizations

Creating Custom Skills

Create a new folder under skills/ with the following files:

skills/
└── my_skill/
    ├── skill.json      # Skill definition (required)
    ├── handler.py      # Python handler (recommended)
    └── prompt.txt      # Prompt template (optional)

skill.json:

{
  "name": "my_skill",
  "description": "What this skill does",
  "version": "1.0.0",
  "parameters": {
    "input": {
      "type": "string",
      "description": "The input to process",
      "required": true
    }
  }
}

handler.py:

def handle(input: str) -> str:
    """Process the input and return a result."""
    return input.upper()

See the Skill Development Guide for details on JavaScript, TypeScript, and binary handlers.

MCP Server Integration

Chatixia supports the Model Context Protocol (MCP) for connecting external tool servers.

Create .mcp.json in the project root:

{
    "mcpServers": {
        "playwright": {
            "command": "npx",
            "args": ["-y", "@playwright/mcp@latest"],
            "description": "Browser automation",
            "enabled": true
        }
    }
}

Option	Required	Description
command	Yes	Command to run (npx, uvx, node, etc.)
args		Command-line arguments
env		Environment variables (API keys, etc.)
description		Human-readable description
enabled		Set to false to disable (default: true)

See .mcp.example.json for more examples.

Project Structure

chatixia-agent/
├── cli/                  # Interactive CLI (REPL + autonomous mode)
├── core/                 # Agent core (skills, sessions, memory, DB, MCP)
├── server/               # FastAPI backend (REST + SSE streaming)
├── web/                  # React frontend (Vite + TypeScript)
├── extension/            # Chrome extension (Manifest V3)
├── sdk/                  # PyPI package (chatixia CLI)
├── skills/               # Skill definitions (26 skills)
├── docs/                 # Documentation (MkDocs Material)
├── tests/                # pytest suite
├── .chatixia/            # Local data (SQLite DB, prompts, uploads)
└── pyproject.toml        # Project configuration

Testing

uv run pytest

Documentation

Full documentation is available at chatixia-ai.github.io/chatixia-agent.

License

MIT

Contributing

Issues and Pull Requests are welcome!