CIRIS Engine

Copyright © 2025 Eric Moore and CIRIS L3C | AGPL-3.0 License

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

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

BETA RELEASE 2.4.2-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 CIRIS_REDDIT_CLIENT_SECRET CIRIS_REDDIT_USERNAME 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 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 29 languages with full pipeline localization - the entire ethical reasoning system operates in the user's preferred language:

Supported Languages: Amharic (am), Arabic (ar), Bengali (bn), Burmese (my), Chinese (zh), English (en), French (fr), German (de), Hausa (ha), Hindi (hi), Indonesian (id), Italian (it), Japanese (ja), Korean (ko), Marathi (mr), Persian (fa), Portuguese (pt), Punjabi (pa), Russian (ru), Spanish (es), Swahili (sw), Tamil (ta), Telugu (te), Thai (th), Turkish (tr), Ukrainian (uk), Urdu (ur), Vietnamese (vi), Yoruba (yo)

What's Localized:

• ACCORD - The complete ethical framework (~1150 lines per language)
• DMA Prompts - All 6 Decision Making Algorithm prompts (PDMA, CSDMA, DSDMA, IDMA, ASPDMA, TSASPDMA)
• Comprehensive Guide - Runtime instructions for the AI
• Conscience Strings - Ponder questions and ethical reflection prompts
• Mobile UI - Full UI localization via localization/*.json

Setting Language:

# Environment variable
export CIRIS_PREFERRED_LANGUAGE=am  # Amharic
ciris-agent --adapter api

# Or set during setup wizard (saved to .env)

Files:

localization/              # Mobile UI strings (JSON)
ciris_engine/data/localized/
├── accord_1.2b_{lang}.txt           # Localized ACCORD
└── CIRIS_COMPREHENSIVE_GUIDE_{lang}.md
ciris_engine/logic/dma/prompts/localized/{lang}/
├── pdma_ethical.yml       # Ethical evaluation
├── csdma_common_sense.yml # Common sense checks
├── dsdma_base.yml         # Domain-specific
├── idma.yml               # Intuition/coherence
├── action_selection_pdma.yml
└── tsaspdma.yml           # Tool selection

Deployment Ready

✅ 22 core services with message bus architecture ✅ 4GB RAM target for edge deployment ✅ Thousands of tests with comprehensive coverage ✅ SonarCloud quality gates passing ✅ Currently powering Discord moderation at agents.ciris.ai ✅ Mobile apps for Android and iOS via unified KMP codebase

Documentation

📚 Complete Documentation Hub

Quick Links:

• Quick Start Guide - Get running in 5 minutes
• Architecture Overview - System design (22 services)
• API Reference - REST API documentation
• Benchmarking - Ethical reasoning metrics via EthicsEngine.org
• Developer Guide - Contributing and extending

Contributing

1. Read the Architecture Guide - Understand the three-legged stool
2. Follow Type Safety Rules - Minimal Dict[str, Any] usage
3. See CONTRIBUTING.md for setup

Support

• Issues: GitHub Issues
• Security: SECURITY.md
• Quality:

---

CIRIS: Core Identity, Integrity, Resilience, Incompleteness, and Signalling Gratitude Ethical AI with human oversight, complete transparency, and deployment reliability.

Ready to build trustworthy AI? → Get started →