Metadata-Version: 2.4
Name: ciris-agent
Version: 1.7.5
Summary: CIRIS: Ethical AI Agent with Consensual Evolution Protocol
Home-page: https://github.com/CIRISAI/CIRISAgent
Author: Eric Moore
Author-email: eric@ciris.ai
Project-URL: Bug Reports, https://github.com/CIRISAI/CIRISAgent/issues
Project-URL: Source, https://github.com/CIRISAI/CIRISAgent
Project-URL: Documentation, https://github.com/CIRISAI/CIRISAgent/tree/main/docs
Keywords: ai agent ethical-ai autonomous-agent discord-bot api-server
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: pydantic<3.0.0,>=2.7.0
Requires-Dist: openai<2.0.0,>=1.0.0
Requires-Dist: instructor<2.0.0,>=1.11.3
Requires-Dist: PyYAML<7.0.0,>=6.0.1
Requires-Dist: psycopg2-binary<3.0.0,>=2.9.0
Requires-Dist: SQLAlchemy<3.0.0,>=2.0.0
Requires-Dist: aiohttp<4.0.0,>=3.9.0
Requires-Dist: httpx<1.0.0,>=0.25.0
Requires-Dist: anyio<5.0.0,>=4.0.0
Requires-Dist: discord.py<3.0.0,>=2.3.0
Requires-Dist: pypdf<7.0.0,>=6.0.0
Requires-Dist: docx2txt<1.0.0,>=0.8
Requires-Dist: cryptography<46.0.0,>=41.0.0
Requires-Dist: PyJWT[crypto]<3.0.0,>=2.8.0
Requires-Dist: bcrypt<5.0.0,>=4.0.0
Requires-Dist: PyNaCl<2.0.0,>=1.5.0
Requires-Dist: fastapi<1.0.0,>=0.111.0
Requires-Dist: uvicorn[standard]<1.0.0,>=0.29.0
Requires-Dist: websockets>=14.0
Requires-Dist: python-multipart<1.0.0,>=0.0.6
Requires-Dist: aiofiles<24.0.0,>=23.2.0
Requires-Dist: python-dotenv<2.0.0,>=1.0.0
Requires-Dist: networkx<4.0,>=3.0
Requires-Dist: psutil<6.0.0,>=5.9.0
Requires-Dist: croniter<3.0.0,>=2.0.0
Requires-Dist: backoff<3.0.0,>=2.2.0
Requires-Dist: zeroconf<1.0.0,>=0.39.0
Requires-Dist: click<9.0.0,>=8.1.0
Requires-Dist: docker<8.0.0,>=6.0.0
Provides-Extra: dev
Requires-Dist: pytest<8.0.0,>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio<1.0.0,>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov<5.0.0,>=4.1.0; extra == "dev"
Requires-Dist: pytest-timeout<3.0.0,>=2.2.0; extra == "dev"
Requires-Dist: pytest-xdist<4.0.0,>=3.3.0; extra == "dev"
Requires-Dist: pytest-rerunfailures<17.0.0,>=16.0.0; extra == "dev"
Requires-Dist: pytest-mock<4.0.0,>=3.12.0; extra == "dev"
Requires-Dist: hypothesis<7.0.0,>=6.0.0; extra == "dev"
Requires-Dist: mypy<2.0.0,>=1.8.0; extra == "dev"
Requires-Dist: types-psutil<6.0.0,>=5.9.0; extra == "dev"
Requires-Dist: types-PyYAML<7.0.0,>=6.0.0; extra == "dev"
Requires-Dist: types-aiofiles<24.0.0,>=23.0.0; extra == "dev"
Requires-Dist: instructor<2.0.0,>=1.11.3; extra == "dev"
Requires-Dist: astunparse<2.0.0,>=1.6.3; extra == "dev"
Requires-Dist: websocket-client<2.0.0,>=1.6.0; extra == "dev"
Requires-Dist: zeroconf<1.0.0,>=0.39.0; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Stable](https://img.shields.io/badge/Status-STABLE-green.svg)](CHANGELOG.md)
[![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=CIRISAI_CIRISAgent&metric=ncloc)](https://sonarcloud.io/summary/new_code?id=CIRISAI_CIRISAgent)
[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=CIRISAI_CIRISAgent&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=CIRISAI_CIRISAgent)
[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=CIRISAI_CIRISAgent&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=CIRISAI_CIRISAgent)

# CIRIS Engine

**Copyright © 2025 Eric Moore and CIRIS L3C** | **Apache 2.0 License**

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

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

**BETA RELEASE 1.7.5-stable** | [Release Notes](CHANGELOG.md) | [Documentation Hub](docs/README.md)

Academic paper https://zenodo.org/records/17195221
Philosophical foundation https://ciris.ai/ciris_covenant.pdf

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, and domain checks
- **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](CLAUDE.md#core-philosophy-type-safety-first)

**Engine Documentation**: [ciris_engine/README.md](ciris_engine/README.md) - Technical architecture and implementation details

## Quick Start

### One-Line Install (Agent + Web UI)

Get CIRIS running in minutes without Docker:

```bash
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](docs/STANDALONE_INSTALL.md)** - Full options, troubleshooting, and manual setup

### Agent-Only Install (Python)

**Via pip (Recommended):**
```bash
# 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):**
```bash
# 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](docs/INSTALLATION.md)** - 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 only |
| 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** (Android only): Available exclusively on Android due to Google Play Services dependencies. 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:**
```bash
# 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:**
```bash
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)

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

## Documentation

**📚 [Complete Documentation Hub](docs/README.md)**

**Quick Links:**
- **[Quick Start Guide](docs/QUICKSTART.md)** - Get running in 5 minutes
- **[Architecture Overview](docs/ARCHITECTURE.md)** - System design (22 services)
- **[API Reference](docs/API_SPEC.md)** - REST API documentation
- **[Developer Guide](docs/FOR_NERDS.md)** - Contributing and extending

## Contributing

1. Read the [Architecture Guide](docs/ARCHITECTURE.md) - Understand the three-legged stool
2. Follow [Type Safety Rules](CLAUDE.md#type-safety) - Minimal `Dict[str, Any]` usage
3. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup

## Support

- **Issues**: [GitHub Issues](https://github.com/CIRISAI/CIRISAgent/issues)
- **Security**: [SECURITY.md](SECURITY.md)
- **Quality**: [![SonarCloud](https://sonarcloud.io/images/project_badges/sonarcloud-light.svg)](https://sonarcloud.io/summary/new_code?id=CIRISAI_CIRISAgent)

---

**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 →](docs/README.md)**
