CIRIS Engine

Core Identity, Integrity, Resilience, Incompleteness, and Signalling Gratitude

A type-safe, auditable AI agent framework with built-in ethical reasoning

BETA RELEASE 2.3.1-stable | Release Notes | Documentation Hub

CIRIS lets you run AI agents that explain their decisions, defer to humans when uncertain, and maintain complete audit trails. Currently powering Discord community moderation, designed to scale to healthcare and education.

What It Actually Does

CIRIS wraps LLM calls with:

Multiple evaluation passes - Every decision gets ethical, common-sense, domain, and epistemic diversity checks
Intuition DMA (IDMA) - Coherence Collapse Analysis for detecting fragile reasoning (k_eff < 2 = single-source dependence)
Human escalation - Uncertain decisions defer to designated "Wise Authorities"
Complete audit trails - Every decision is logged with reasoning
Type safety - Minimal Dict[str, Any] usage, none in critical paths
Identity system - Agents have persistent identity across restarts
Privacy compliance - Built-in DSAR/GDPR tools for data discovery, export, and deletion
Commons Credits - Track non-monetary contributions that strengthen community (not currency, not scorekeeping)

Philosophy: "No Untyped Dicts, No Bypass Patterns, No Exceptions" - See CLAUDE.md

For AI Assistants: See llms.txt for quick context and docs/OVERVIEW.md for architecture.

Engine Documentation: ciris_engine/README.md - Technical architecture and implementation details

Ethical Reasoning Benchmarks: docs/BENCHMARKING.md - How we measure drift via EthicsEngine.org (CIRIS + Maverick: 82.1% ±2.4% on HE-300)

Quick Start

One-Line Install (Agent + Web UI)

Get CIRIS running in minutes without Docker:

curl -sSL https://ciris.ai/install.sh | bash

This installs both CIRISAgent and CIRISGUI with all dependencies, then opens the web interface at http://localhost:3000.

→ Standalone Installation Guide - Full options, troubleshooting, and manual setup

Agent-Only Install (Python)

Via pip (Recommended):

# Install from PyPI
pip install ciris-agent

# Start with API adapter and built-in web UI
ciris-agent --adapter api --port 8000

# Or use Discord adapter
ciris-agent --adapter discord --guild-id YOUR_GUILD_ID

# Load multiple adapters together
ciris-agent --adapter api --adapter reddit

From Source (Development):

# 1. Clone and install
git clone https://github.com/CIRISAI/CIRISAgent.git
cd CIRISAgent
pip install -r requirements.txt
# For development: pip install -r requirements-dev.txt

# 2. Start with Discord adapter
python main.py --adapter discord --guild-id YOUR_GUILD_ID

# 3. Or start API mode
python main.py --adapter api --port 8000

# 4. Load multiple adapters together
python main.py --adapter api --adapter reddit

→ Complete Installation Guide - Detailed setup, configuration, and deployment

Available Adapters

CIRIS supports both built-in and modular adapters that can be loaded via --adapter flag or CIRIS_ADAPTER environment variable.

Built-in Adapters

| Adapter | Type | Description | Usage | |---------|------|-------------|-------| | CLI | Communication | Interactive command-line interface | --adapter cli | | API | Communication | RESTful HTTP API server (FastAPI) | --adapter api --port 8000 | | Discord | Communication | Discord bot integration | --adapter discord --guild-id ID |

Modular Service Adapters

| Adapter | Type | Description | Required Configuration | Usage | |---------|------|-------------|------------------------|-------| | Reddit | Communication + Tools | Reddit integration for r/ciris monitoring and interaction. Supports posting, commenting, content removal, user lookups, and passive observation. | CIRIS_REDDIT_CLIENT_ID<br>CIRIS_REDDIT_CLIENT_SECRET<br>CIRIS_REDDIT_USERNAME<br>CIRIS_REDDIT_PASSWORD | --adapter reddit | | SQL External Data | Tools | DSAR/GDPR compliance tools for SQL databases. Supports data discovery, export, anonymization, and deletion across multiple database types (SQLite, PostgreSQL, MySQL, MSSQL). | Database connection config (see docs) | Loaded automatically via tool system | | Mock LLM | LLM Provider | Testing mock LLM service that simulates AI responses without external API calls. Not for production use. | None (optional delay/failure rate) | --adapter mockllm or --mock-llm | | Geo Wisdom | Wise Authority | Geographic navigation guidance using OpenStreetMap for routing and geocoding. | None (uses public OSM API) | Loaded automatically for navigation domains | | Weather Wisdom | Wise Authority | Weather forecasting and alerts using NOAA National Weather Service API. | None (uses public NOAA API) | Loaded automatically for weather domains | | Sensor Wisdom | Wise Authority | Home automation and IoT sensor integration via Home Assistant. Actively filters out medical sensors. | CIRIS_HOMEASSISTANT_URL<br>CIRIS_HOMEASSISTANT_TOKEN | Loaded automatically for sensor domains |

LLM Providers

CIRIS uses an OpenAI-compatible API interface for LLM inference:

| Provider | Endpoint | Authentication | Platform | |----------|----------|----------------|----------| | ciris.ai | https://ciris.ai/v1 | Google Sign-In | Android, iOS | | OpenAI | https://api.openai.com/v1 | API Key | All | | Groq | https://api.groq.com/openai/v1 | API Key | All | | Together.ai | https://api.together.ai/v1 | API Key | All | | Local LLMs | http://localhost:8080/v1 | Optional | All |

ciris.ai Proxy (Mobile): Available on Android and iOS via the unified KMP mobile app. Uses Google Sign-In for authentication with automatic token refresh. No logging - prompts and responses pass through without being stored. Backend providers are Groq and Together.ai.

Agent Templates

CIRIS includes pre-configured agent templates in ciris_engine/ciris_templates/:

| Template | Description | |----------|-------------| | Ally | Personal assistant focused on ethical partnership. Supports task management, scheduling, decision support, and wellbeing. Includes California SB 243 compliance, crisis response protocols, and GDPR DSAR automation. | | Datum | Community moderation agent for Discord. Production-deployed at agents.ciris.ai. |

Templates define identity, permitted actions, guardrails, and standard operating procedures (SOPs) for DSAR compliance.

Loading Adapters

Via Command Line:

# Single adapter
python main.py --adapter api

# Multiple adapters
python main.py --adapter api --adapter reddit

# With configuration
export CIRIS_REDDIT_CLIENT_ID="your_client_id"
export CIRIS_REDDIT_CLIENT_SECRET="your_secret"
python main.py --adapter reddit

Via Environment Variable:

export CIRIS_ADAPTER="api,reddit"
python main.py

Priority and Behavior:

Communication adapters can run simultaneously (e.g., API + Reddit + Discord)
Reddit adapter defaults to lower priority than API for message handling
Wise Authority adapters load automatically when their domain is needed
Mock LLM disables real LLM services when loaded (testing only)

Mobile Apps

CIRIS provides native mobile apps for Android and iOS via Kotlin Multiplatform (KMP):

mobile/                    # Unified KMP codebase
├── shared/               # Shared Kotlin code (ViewModels, API, UI)
├── androidApp/           # Android-specific code
└── iosApp/               # iOS-specific code (SwiftUI shell)

Key Features:

Unified Codebase: Single Kotlin codebase for both platforms via Compose Multiplatform
Setup Wizard: 4-step guided setup with LLM configuration and optional features
Accord Metrics Consent: Explicit opt-in for AI alignment research (anonymous metrics only)
Google Sign-In: Free CIRIS AI proxy access with Google authentication
BYOK Mode: Bring Your Own Key for OpenAI, Anthropic, Groq, Together.ai, or local LLMs

Building:

# Android
cd mobile && ./gradlew :androidApp:assembleDebug

# iOS (requires Xcode)
cd mobile/iosApp && xcodebuild -scheme iosApp

→ Mobile Development Guide - Full build instructions and architecture

Localization

CIRIS supports 14 languages with full pipeline localization - the entire ethical reasoning system operates in the user's preferred language:

Supported Languages: Amharic (am), Arabic (ar), Chin

CIRISAgent

Install / Use

README