Metadata-Version: 2.4
Name: ciri-ai
Version: 0.0.8
Summary: CIRI Copilot — a local AI agent CLI with skills, toolkits, and subagents
Project-URL: Homepage, https://github.com/adimis-ai/ciri
Project-URL: Repository, https://github.com/adimis-ai/ciri
Project-URL: Issues, https://github.com/adimis-ai/ciri/issues
Project-URL: Changelog, https://github.com/adimis-ai/ciri/releases
Author-email: Aditya Mishra <adimis.ai.001@gmail.com>
License: # MIT License
        
        Copyright (c) 2026 Aditya Mishra
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE.md
Keywords: agent,ai,automation,cli,copilot,langchain,langgraph,llm,skills,subagents,toolkits
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: anyio
Requires-Dist: asgiref>=3.11.1
Requires-Dist: black>=26.1.0
Requires-Dist: crawl4ai
Requires-Dist: ddgs
Requires-Dist: deepagents
Requires-Dist: duckduckgo-search
Requires-Dist: httpx
Requires-Dist: importlib-metadata; python_version < '3.13'
Requires-Dist: langchain
Requires-Dist: langchain-anthropic>=1.3.1
Requires-Dist: langchain-cohere>=0.5.0
Requires-Dist: langchain-community
Requires-Dist: langchain-core
Requires-Dist: langchain-deepseek>=1.0.1
Requires-Dist: langchain-fireworks>=1.1.0
Requires-Dist: langchain-google-genai>=4.2.0
Requires-Dist: langchain-groq>=1.1.2
Requires-Dist: langchain-litellm>=0.5.1
Requires-Dist: langchain-mcp-adapters
Requires-Dist: langchain-mistralai>=1.1.1
Requires-Dist: langchain-ollama>=1.0.1
Requires-Dist: langchain-openai
Requires-Dist: langchain-openrouter>=0.0.2
Requires-Dist: langchain-together>=0.0.2.post1
Requires-Dist: langchain-unstructured
Requires-Dist: langgraph
Requires-Dist: langgraph-checkpoint-sqlite
Requires-Dist: langgraph-swarm>=0.1.0
Requires-Dist: lxml>=5.4.0
Requires-Dist: openai
Requires-Dist: opentelemetry-api
Requires-Dist: opentelemetry-exporter-otlp
Requires-Dist: opentelemetry-sdk
Requires-Dist: orjson
Requires-Dist: packaging
Requires-Dist: platformdirs
Requires-Dist: playwright>=1.58.0
Requires-Dist: prompt-toolkit>=3.0.52
Requires-Dist: pydantic
Requires-Dist: python-dotenv
Requires-Dist: pyyaml
Requires-Dist: rich
Requires-Dist: sqlalchemy
Requires-Dist: sqlite-vec
Requires-Dist: structlog
Requires-Dist: tenacity
Requires-Dist: typer[all]
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: build; extra == 'dev'
Requires-Dist: cyclonedx-bom; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pip-audit; extra == 'dev'
Requires-Dist: pyinstaller; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Requires-Dist: types-requests; extra == 'dev'
Provides-Extra: encrypted
Requires-Dist: pysqlcipher3; extra == 'encrypted'
Description-Content-Type: text/markdown

# CIRI Copilot

[![PyPI version](https://img.shields.io/pypi/v/ciri.svg)](https://pypi.org/project/ciri/)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.md)
[![uv](https://img.shields.io/badge/built%20with-uv-blueviolet)](https://docs.astral.sh/uv/)

**CIRI (Contextual Intelligent Runtime Interface) Copilot** — a local, desktop-class AI copilot that runs as a command-line interface (CLI). It provides interactive chat with AI models, thread-based conversation management, file- and skill-aware autocompletion, and an extensible skills/toolkit system.

This README is intentionally neutral and written for both developers and non-developers: what the project does, how to get started, how to configure it, and key implementation notes and limitations.

---

## Table of Contents

- [What CIRI is (brief)](#what-ciri-is-brief)
- [Features](#features)
- [Who should use it](#who-should-use-it)
- [Prerequisites](#prerequisites)
  - [Windows](#windows)
  - [macOS](#macos)
  - [Linux](#linux)
- [Installation](#installation)
  - [Clone the repo](#clone-the-repo)
  - [Install (global vs development)](#install-global-vs-development)
- [Configuration](#configuration)
  - [OpenRouter API key](#openrouter-api-key)
- [Quickstart](#quickstart)
- [API Mode (Programmatic Access)](#api-mode-programmatic-access)
- [Commands reference (short)](#commands-reference-short)
- [Developer notes](#developer-notes)
- [Limitations & privacy](#limitations--privacy)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#license)
- [Contact](#contact)

---

## What CIRI is (brief)

CIRI is a local CLI application that helps users interact with AI models and tools from their terminal. It uses OpenRouter (or compatible providers) for model access and aims to balance interactivity, local storage, and extensibility via "skills" and toolkits.

## Features

- **Interactive AI Chat**: Streaming responses with rich terminal formatting.
- **Multi-Provider Support**: Seamless integration with OpenRouter or direct providers (Anthropic, OpenAI, Google, etc.) via LangChain.
- **Multimodal Content**: Support for images, audio, and documents (PDF, CSV, etc.) in conversation.
- **Thread-Based Management**: Save, switch, and delete conversation threads locally.
- **Deep Contextual Autocompletion**: High-performance autocompletion for `@files:`, `@folders:`, `@skills:`, `@toolkits:`, `@subagents:`, and `@harness:`.
- **Self-Evolution**: Ciri can analyze its workspace and register new skills, toolkits, and subagents on the fly.
- **Human-in-the-Loop (HITL)**: Approve, reject, or edit tool actions (shell commands, file edits) before they execute.
- **Local Storage**: Checkpoint and conversation history stored in a local SQLite database.
- **Extensible Architecture**: Easily add new skills and toolkits.
- **Programmatic API Mode**: `--api` mode provides a persistent server with Unix socket interface for building custom UIs and backend integrations. Supports streaming events, thread state queries, and model/browser profile switching.

## Who should use it

- Non-developers: a lightweight, local AI chat assistant accessible from the terminal.
- Developers: a base to extend with new skills, integrate tools, or customize model usage.

## Prerequisites

Minimum recommended: **Python 3.12+** (project developed and tested on 3.12). Adjust or test if you need earlier versions.

### Windows

- Git
- Python 3.12+ (check "Add Python to PATH" during install)
- uv (https://docs.astral.sh/uv/)

PowerShell (install uv):

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

### macOS

- Git (Xcode Command Line Tools or Homebrew)
- Python 3.12+ (Homebrew: `brew install python@3.12`)

Install uv:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

### Linux (Ubuntu/Debian example)

```bash
sudo apt update && sudo apt upgrade -y
sudo apt install git -y
# If Python 3.12 is not available, consider using the deadsnakes PPA on Ubuntu:
# sudo add-apt-repository ppa:deadsnakes/ppa -y
# sudo apt update
# sudo apt install python3.12 python3.12-venv python3.12-dev -y

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
```

---

## Installation

### From PyPI (recommended)

```bash
pip install ciri-ai
```

Or with [uv](https://docs.astral.sh/uv/):

```bash
# Install as a global tool (recommended)
uv tool install ciri-ai --force --refresh

# Or add to your current project
uv add ciri-ai
```

After install, the `ciri` command is available globally.

### From source

Clone the repo:

```bash
git clone https://github.com/adimis-ai/ciri.git
cd ciri
```

Option 1 — Global install from source (recommended for users):

```bash
uv tool install .
```

This places the `ciri` command into your user bin (commonly `~/.local/bin`) and isolates dependencies.

Option 2 — Development / editable (recommended for contributors):

```bash
# create and sync virtual environment with uv
uv sync

# install package in editable mode
uv pip install -e .
```

---

## Configuration

### API Keys

CIRI supports multiple providers. By default, it uses **OpenRouter**, but you can use any provider supported by LangChain (OpenAI, Anthropic, Google, Mistral, etc.).

- **Interactive Setup**: If an API key is missing for your chosen model, CIRI will prompt you to enter it on startup and offer to persist it globally in `~/.ciri/.env` and your shell profile.
- **Environment Variables**: You can also set them manually:
  ```bash
  export OPENROUTER_API_KEY="your-key"
  export ANTHROPIC_API_KEY="your-key"
  # etc.
  ```

### Model Gateway

You can switch between `langchain` (default) and `openrouter` gateways via the `LLM_GATEWAY_PROVIDER` variable.

```bash
export LLM_GATEWAY_PROVIDER="langchain" # Supports provider:model format
```

**Security note:** do not commit API keys to version control.

---

## Quickstart

Start the CLI:

```bash
ciri
```

On first run, you will be guided through model and browser profile selection.

### Common interactions

- **Reference Files**: Type `@files:` then a path fragment.
- **Reference Folders**: Type `@folders:` then a path fragment.
- **Reference Harness**: Type `@harness:` to select core or project harness directories — shown with `(Core)` and `(Current)` flags.
- **Use Skills**: Type `@skills:` to see available local skills.
- **Sync Workspace**: Run `/sync` to let Ciri discover your local setup.
- **Change Model**: Run `/change-model` to switch AI providers/models.
- **Manage Threads**: Use `/threads` to list or `/new-thread` to start fresh.

Example session

```text
You> Hello, analyze the @src/__main__.py file
CIRI> [analysis about the file]

You> /threads
# shows list of threads

You> exit
Goodbye!
```

---

## API Mode (Programmatic Access)

For building custom UIs or backend integrations, use the **`--api` mode** with a persistent Unix socket server:

```bash
# Start the API server (holds copilot in memory)
ciri --api --server &

# Send commands from your backend/UI
ciri --api --run --input '{"messages": [{"type": "human", "content": "Hello"}]}'
ciri --api --state --config '{"configurable": {"thread_id": "..."}}'
ciri --api --history --config '{"configurable": {"thread_id": "..."}}'
ciri --api --change-model 'anthropic/claude-opus-4-6'
ciri --api --change-browser-profile '{"browser": "chrome", "profile_directory": "Default"}'
```

All responses are **NDJSON** (newline-delimited JSON) streamed to stdout. The server auto-starts if needed.

→ [Full API Reference](docs-site/docs/api-reference.md)

---

## Commands Reference

| Command | Description |
| :--- | :--- |
| `/threads` | List all conversation threads. |
| `/switch-thread` | Interactively switch to another thread. |
| `/new-thread` | Start a new conversation thread. |
| `/delete-thread` | Delete the current thread history. |
| `/change-model` | Change the active LLM model. |
| `/change-browser-profile` | Switch browser profiles for research. |
| `/sync` | Analyze workspace & register skills/subagents. |
| `/help` | Show the help menu. |
| `/exit` | Exit the CLI. |

**Keyboard shortcuts**

- `Tab` — autocomplete file paths, skills, or model names
- `Ctrl+C` — cancel current operation

---

## Developer notes

**High-level architecture**

- Entry point / CLI: `ciri` starts an interactive REPL-like chat.
- Core Logic: `CopilotController` manages threads and executes the agent graph (supports multimodal inputs).
- Model integration: OpenRouter client used for model calls; streaming and selection handled by runtime code.
- Tools & skills: extensible skills discovered under `.ciri/skills` (skills may include scripts, validators, and metadata).
- Storage: local conversation storage — see code for details.

**Key locations**

- `src/` — main package and CLI entry points (look for `__main__.py` or CLI module)
- `.ciri/skills` — bundled skills and examples
- `tests/` — test suite
- `pyproject.toml` — project metadata and dependencies

**Extending**

- Follow patterns used in `.ciri/skills` to add new skills
- Document inputs/outputs and add tests under `tests/`

**Development tips**

- Use `uv sync` to prepare the development environment
- Install editable: `uv pip install -e .`

---

## Limitations & privacy

- CIRI relies on third-party model providers (OpenRouter). Provider policies, costs, and behavior apply.
- Conversations are stored locally, but model requests are sent over the network to the chosen provider. Avoid sending sensitive data unless you accept the provider's terms.
- Offline use requires configuring or running compatible local models — not provided by default.

---

## Troubleshooting

**Command `ciri` not found**

Cause: user bin (e.g., `~/.local/bin`) not in `PATH`.

Fix (Linux/macOS):

```bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profile
# or add to ~/.bashrc or ~/.zshrc and restart the shell
```

**Python version error**

Cause: Python < 3.12 installed. Install Python 3.12+ and ensure `uv` or your environment uses it.

**API key errors**

Cause: invalid or missing OpenRouter API key. Verify at https://openrouter.ai/keys and re-enter when prompted. Remove saved key files if needed (e.g., `~/.ciri/.env`).

**Permission denied when writing data**

Cause: incorrect ownership of `~/.ciri` or other data directories.

Fix (Linux):

```bash
sudo chown -R "$USER":"$USER" ~/.ciri
```

---

## Contributing

Contributions welcome. See `CONTRIBUTING.md`.

Suggested flow:

1. Fork and create a branch
2. Run tests and add tests for new behavior
3. Open a PR with a clear description

---

## License

MIT — see `LICENSE.md`.

---

## Contact

Aditya Mishra — https://github.com/adimis-ai

Project: https://github.com/adimis-ai/ciri

