# Chatixia

[![Python](https://img.shields.io/badge/Python-3.14+-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
[![PyPI](https://img.shields.io/pypi/v/chatixia?style=flat-square)](https://pypi.org/project/chatixia/)
[![Azure OpenAI](https://img.shields.io/badge/Azure%20OpenAI-Powered-0078D4?style=flat-square&logo=microsoft-azure&logoColor=white)](https://azure.microsoft.com/products/ai-services/openai-service)
[![Docs](https://img.shields.io/badge/Docs-GitHub%20Pages-blue?style=flat-square)](https://chatixia-ai.github.io/chatixia-agent/)

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

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

See the [SDK documentation](https://chatixia-ai.github.io/chatixia-agent/sdk/) for the full guide.

## Full Platform Setup

### Prerequisites

- Python 3.14+
- [uv](https://docs.astral.sh/uv/) package manager
- Node.js 20+ (for the Web UI)

### Installation

```bash
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`:

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

```bash
# 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:**

```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:**

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

See the [Skill Development Guide](https://chatixia-ai.github.io/chatixia-agent/skill-development-guide/) for details on JavaScript, TypeScript, and binary handlers.

## MCP Server Integration

Chatixia supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for connecting external tool servers.

Create `.mcp.json` in the project root:

```json
{
    "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

```bash
uv run pytest
```

## Documentation

Full documentation is available at [chatixia-ai.github.io/chatixia-agent](https://chatixia-ai.github.io/chatixia-agent/).

## License

MIT

## Contributing

Issues and Pull Requests are welcome!
