Integrations & Adapters

CIRIS connects to your world through adapters. Each adapter is a self-contained integration that provides tools or communication channels.

Adapter Architecture

Message Bus: Adapters communicate via typed message buses (Tool, Communication, RuntimeControl)

Multi-Adapter: Run CLI + API + Discord + Home Assistant simultaneously in the same process

Type-Safe: All data flows through Pydantic schemas. No untyped dicts, no bypass patterns.

Self-Contained: Each adapter includes its own schemas, protocols, and configuration wizard

Communication Adapters

Primary interfaces for interacting with CIRIS

CLI Adapter

Interactive command-line interface. Launch with --adapter cli. Perfect for development, testing, and direct terminal interaction. Supports mock LLM for offline testing.

API Adapter

RESTful HTTP server built with FastAPI. Launch with --adapter api --port 8000. Provides web UI, OAuth2 authentication, and multi-tenant support. Best for service integration.

Discord Adapter

Full Discord bot integration for community moderation. Launch with --adapter discord --guild-id YOUR_GUILD_ID. Persistent graph storage and real LLM providers with fallback.

Platform Adapters

Deep integrations with specific platforms

Home Assistant + CIRISHome

Under Development

Complete multi-modal home automation with 100% local AI processing. Voice control, camera analysis, and smart automation — no cloud required.

Capabilities:

Voice commands via Wyoming protocol
Device control (lights, switches, climate, locks)
Local vision processing with Llama-4-Scout
Camera snapshot analysis
Enriches context with entity states
Text-to-speech via Coqui TTS

Hardware Stack:

Home Assistant Yellow (automation hub)
Jetson Orin Nano (local AI processing)
Voice PE Pucks (voice satellites)

HACS Installation:

Install HACS in Home Assistant
Add repository: https://github.com/CIRISAI/CIRISHome
Install "CIRISHome Agent" add-on
Configure with Jetson IP and HA token

Full Installation Guide →

Full Reddit integration with posting, commenting, and content moderation. Built-in GDPR compliance, AI transparency disclosure, and deletion compliance.

Capabilities:

Submit posts and comments
Submission and user context lookups
Active observation mode
Content removal and moderation
Automatic AI transparency disclosure

Data & Infrastructure

Database access and external data sources

External Data SQL

DSAR/GDPR compliance tools for SQL databases. Privacy schema support, dialect-specific implementations (PostgreSQL, MySQL, SQLite), and structured data access.

Coming Soon

Adapters currently under development

MCP Server

Model Context Protocol server. Expose CIRIS tools to MCP-compatible clients.

MCP Client

Connect to external MCP servers for additional tool capabilities.

Weather

Weather forecasting via NOAA National Weather Service API.

Navigation

Geographic routing and directions via OpenStreetMap.

Utility Adapters

Testing, metrics, and hosted services

Mock LLM

Testing mock that simulates LLM responses without external API calls. Perfect for development, CI/CD pipelines, and offline testing.

Covenant Metrics

Privacy-first metrics collection for CIRISLens observability. Requires explicit user consent. Reports WBD (Wisdom-Based Deferral) and PDMA decision events.

Hosted Tools

Access to CIRIS-hosted tool integrations. Extensible registry for cloud-based capabilities.

Building New Adapters

CIRIS adapters are self-contained Python packages. Start from the sample_adapter template and implement your integration.

Required Files

your_adapter/
├── manifest.json      # Service declaration & metadata
├── adapter.py         # Main adapter class
├── service.py         # Service implementations
├── protocol.py        # Protocol definitions
├── schemas.py         # Pydantic data models
├── configurable.py    # Configuration wizard
└── __init__.py        # Package init with Adapter export

Service Types

TOOL

Provides capabilities. Implement execute_tool() and get_available_tools().

COMMUNICATION

Handles messaging. Implement send_message() and fetch_messages().

manifest.json Structure

{
  "name": "your_adapter",
  "version": "1.0.0",
  "description": "Your adapter description",
  "services": [
    {
      "type": "TOOL",
      "capabilities": ["tool:your_adapter:action"]
    }
  ],
  "configuration": {
    "steps": [
      {"step_id": "discover", "type": "discovery"},
      {"step_id": "auth", "type": "oauth"},
      {"step_id": "settings", "type": "input"},
      {"step_id": "confirm", "type": "confirm"}
    ]
  }
}

Adapter Implementation

from ciris_engine.logic.adapters.base import Service
from ciris_engine.schemas.adapter import AdapterServiceRegistration

class YourAdapter(Service):
    def __init__(self, runtime, context=None):
        self.runtime = runtime
        self.tool_service = YourToolService(runtime)

    def get_services_to_register(self):
        return [
            AdapterServiceRegistration(
                service_type=ServiceType.TOOL,
                provider=self.tool_service,
                priority=Priority.NORMAL,
                capabilities=["tool:your_adapter:action"]
            )
        ]

    async def start(self):
        await self.tool_service.start()

    async def stop(self):
        await self.tool_service.stop()

# Required export
Adapter = YourAdapter

Configuration Step Types

discovery

Auto-detect services on network

oauth

OAuth2 with PKCE flow

select

Multiple-choice selection

input

Manual text/config entry

confirm

Review and approve final configuration

Adapter Design Principles

Type-Safe Everything

Use Pydantic schemas for all data structures. No untyped dicts, no exceptions.

No Bypass Patterns

Strict protocol adherence. All communication flows through the message bus.

Self-Contained

All code, schemas, and protocols live in one directory. No external dependencies on other adapters.

Graceful Lifecycle

Proper async start/stop methods. Clean up resources, close connections, cancel tasks.

Ready to build your own adapter?

View Sample Adapter Read the Docs