ciris-agent 1.7.7__py3-none-any.whl

ciris_adapters/README.md

@@ -0,0 +1,113 @@
+# CIRIS Modular Services
+
+This directory contains modular services that can be dynamically loaded into CIRIS.
+
+## Philosophy
+
+Services should be:
+- **Self-contained**: All code, schemas, and protocols in one directory
+- **Declarative**: manifest.json describes the service
+- **Protocol-compliant**: Implement standard CIRIS protocols
+- **Zero backwards compatibility**: Move forward only
+
+## Directory Structure
+
+```
+ciris_adapters/
+├── mock_llm/              # Example: Mock LLM service (test only)
+├── your_service/          # Your modular service here
+└── README.md              # This file
+```
+
+## Creating a Modular Service
+
+### 1. Create Directory Structure
+
+```
+your_service/
+├── manifest.json          # REQUIRED: Service declaration
+├── protocol.py            # REQUIRED: Protocol definition
+├── schemas.py             # REQUIRED: Pydantic schemas
+├── service.py             # REQUIRED: Implementation
+├── __init__.py            # REQUIRED: Package init
+└── README.md              # RECOMMENDED: Documentation
+```
+
+### 2. Write manifest.json
+
+```json
+{
+  "service": {
+    "name": "YourService",
+    "version": "1.0.0",
+    "type": "CUSTOM",
+    "priority": "NORMAL",
+    "description": "What your service does"
+  },
+  "capabilities": ["capability1", "capability2"],
+  "dependencies": {
+    "protocols": ["ciris_engine.protocols.services.ServiceProtocol"],
+    "schemas": ["ciris_engine.schemas.runtime.models"]
+  },
+  "exports": {
+    "service_class": "your_service.service.YourService",
+    "protocol": "your_service.protocol.YourServiceProtocol",
+    "schemas": "your_service.schemas"
+  }
+}
+```
+
+### 3. Implement Protocol
+
+Your protocol should extend appropriate CIRIS base protocols:
+
+```python
+from ciris_engine.protocols.services import ServiceProtocol
+
+class YourServiceProtocol(ServiceProtocol, Protocol):
+    async def your_method(self) -> None: ...
+```
+
+### 4. Define Schemas
+
+Use Pydantic for all data structures:
+
+```python
+from pydantic import BaseModel
+
+class YourConfig(BaseModel):
+    setting: str = "default"
+```
+
+### 5. Implement Service
+
+```python
+class YourService(YourServiceProtocol):
+    async def start(self) -> None:
+        await super().start()
+        # Your initialization
+```
+
+## Loading
+
+Modular services are loaded at runtime when:
+1. Placed in this directory
+2. Have valid manifest.json
+3. Dependencies are satisfied
+4. No conflicts with core services
+
+## Guidelines
+
+- **Test services**: Set `"test_only": true` in manifest
+- **Production services**: Must pass security review
+- **External dependencies**: Declare in manifest
+- **Configuration**: Use schemas, not dicts
+- **Protocols**: Always implement base protocols
+- **No backwards compatibility**: Version via manifest
+
+## Examples
+
+- `mock_llm/` - Mock LLM for testing (first modular service)
+- `geo_wisdom/` - Geographic navigation via OpenStreetMap (safe domain)
+- `weather_wisdom/` - Weather advisories via NOAA API (safe domain)
+- `sensor_wisdom/` - IoT sensor interpretation via Home Assistant (safe domain, filters medical sensors)

ciris_adapters/__init__.py

@@ -0,0 +1,30 @@
+"""
+CIRIS Modular Services - Pluggable service adapters.
+
+This package contains optional service modules that can be dynamically loaded:
+- mock_llm: Mock LLM service for testing
+- reddit: Reddit communication adapter and tools
+- geo_wisdom: Geographic navigation wise authority
+- weather_wisdom: Weather forecasting wise authority
+- sensor_wisdom: Home automation sensor integration
+- external_data_sql: GDPR/DSAR SQL database tools
+- mcp_client: MCP client adapter for connecting to external MCP servers
+- mcp_server: MCP server adapter for exposing CIRIS as an MCP server
+- mcp_common: Shared utilities for MCP client and server
+- ciris_covenant_metrics: Covenant compliance metrics for CIRISLens (opt-in required)
+
+These modules are discovered at runtime via the service loader mechanism.
+"""
+
+__all__ = [
+    "mock_llm",
+    "reddit",
+    "geo_wisdom",
+    "weather_wisdom",
+    "sensor_wisdom",
+    "external_data_sql",
+    "mcp_client",
+    "mcp_server",
+    "mcp_common",
+    "ciris_covenant_metrics",
+]

ciris_adapters/ciris_covenant_metrics/README.md

@@ -0,0 +1,144 @@
+# CIRIS Covenant Metrics Adapter
+
+This adapter provides covenant compliance metrics collection for CIRISLens, reporting WBD (Wisdom-Based Deferral) events and PDMA decision events as specified in the CIRIS Covenant Section II.
+
+## Privacy-First Design
+
+**CRITICAL**: This adapter requires **EXPLICIT opt-in** via the setup wizard. No data is collected or sent without your consent.
+
+### What Data is Collected
+
+When you consent, the following data is sent to CIRISLens:
+
+#### WBD (Wisdom-Based Deferral) Events
+Per CIRIS Covenant Section II, Chapter 3:
+```json
+{
+  "event_type": "wbd_deferral",
+  "timestamp": "2025-12-15T14:00:00Z",
+  "agent_id": "abc123def456...",  // Anonymized hash
+  "thought_id": "thought-123",
+  "task_id": "task-456",
+  "reason": "Ethical uncertainty...",  // Truncated to 200 chars
+  "defer_until": "2025-12-15T15:00:00Z",
+  "priority": "medium"
+}
+```
+
+#### PDMA Decision Events
+Per CIRIS Covenant Section II, Chapter 2:
+```json
+{
+  "event_type": "pdma_decision",
+  "timestamp": "2025-12-15T14:00:00Z",
+  "agent_id": "abc123def456...",  // Anonymized hash
+  "thought_id": "thought-123",
+  "selected_action": "SPEAK",
+  "rationale": "User requested...",  // Truncated to 200 chars
+  "reasoning_summary": "..."  // Truncated to 500 chars
+}
+```
+
+### What is NOT Collected
+
+- User messages or conversation content
+- Personal identifiable information (PII)
+- Chat history
+- Tool call details or parameters
+- External API responses
+- File contents
+
+### Privacy Controls
+
+1. **Anonymization**: Agent IDs are SHA-256 hashed
+2. **Truncation**: All text fields are truncated to prevent sensitive data leakage
+3. **No PII**: Only structural metadata is collected
+4. **Consent Required**: Nothing is sent without explicit consent
+5. **Revocable**: Disable the adapter to stop collection immediately
+
+## Usage
+
+### 1. Load the Adapter
+
+```bash
+python main.py --adapter api --adapter ciris_covenant_metrics
+```
+
+### 2. Complete Setup Wizard
+
+The adapter requires completing the setup wizard which includes:
+
+1. **Data Disclosure**: Review exactly what data will be collected
+2. **Explicit Consent**: Check the consent box (required)
+3. **Endpoint Config**: Configure CIRISLens URL (optional, has default)
+4. **Confirmation**: Review and enable
+
+### 3. Verify Status
+
+Check adapter status via the API:
+```bash
+curl http://localhost:8000/v1/system/adapters/ciris_covenant_metrics
+```
+
+## Configuration
+
+Environment variables:
+- `CIRIS_LENS_ENDPOINT`: CIRISLens API URL (default: `https://lens.ciris.ai/v1`)
+
+Wizard configuration:
+- `consent_given`: Boolean - must be true to collect data
+- `consent_timestamp`: ISO timestamp when consent was given
+- `batch_size`: Number of events to batch (1-100, default: 10)
+- `flush_interval_seconds`: Seconds between batch sends (10-300, default: 60)
+
+## How It Works
+
+### WBD Event Collection
+
+1. Adapter registers as a `WISE_AUTHORITY` service with `send_deferral` capability
+2. When any component calls `WiseBus.send_deferral()`, it broadcasts to ALL services with this capability
+3. The CovenantMetricsService receives the deferral and queues it for transmission
+4. Events are batched and sent to CIRISLens API
+
+### Event Batching
+
+- Events are queued in memory
+- Sent when batch reaches `batch_size` OR `flush_interval_seconds` elapsed
+- Failed batches are re-queued up to 10x batch size
+- All events are flushed on adapter stop
+
+## Revoking Consent
+
+To stop data collection:
+
+1. **Via Setup Wizard**: Re-run wizard and uncheck consent
+2. **Disable Adapter**: Remove from command line arguments
+3. **Immediate**: Data collection stops immediately when consent is revoked
+
+## CIRISLens API
+
+Events are sent to:
+```
+POST {endpoint}/covenant/events
+```
+
+Request body:
+```json
+{
+  "events": [...],
+  "batch_timestamp": "2025-12-15T14:00:00Z",
+  "consent_timestamp": "2025-12-15T13:00:00Z"
+}
+```
+
+## Covenant References
+
+- **Section II, Chapter 2**: Principled Decision-Making Algorithm (PDMA)
+- **Section II, Chapter 3**: Wisdom-Based Deferral (WBD)
+
+For more information about the CIRIS Covenant, see: https://ciris.ai/covenant
+
+## Support
+
+- Privacy Policy: https://ciris.ai/privacy
+- Issues: https://github.com/CIRISAI/CIRISAgent/issues

ciris_adapters/ciris_covenant_metrics/__init__.py

@@ -0,0 +1,36 @@
+"""
+CIRIS Covenant Metrics Adapter.
+
+This adapter provides covenant compliance metrics collection for CIRISLens,
+reporting WBD (Wisdom-Based Deferral) events and PDMA decision events.
+
+CRITICAL REQUIREMENTS:
+1. NOT auto-loaded - Must be explicitly enabled via --adapter
+2. Requires EXPLICIT consent via setup wizard
+3. No data sent without consent
+
+Usage:
+    # Load the covenant metrics adapter
+    python main.py --adapter api --adapter ciris_covenant_metrics
+
+    # Then complete the setup wizard to grant consent
+
+Example importing for custom usage:
+    from ciris_adapters.ciris_covenant_metrics import (
+        Adapter,  # BaseAdapterProtocol-compliant wrapper
+        CovenantMetricsAdapter,
+        CovenantMetricsService,
+    )
+"""
+
+from .adapter import CovenantMetricsAdapter
+from .services import CovenantMetricsService
+
+# Export as Adapter for load_adapter() compatibility
+Adapter = CovenantMetricsAdapter
+
+__all__ = [
+    "Adapter",  # Primary export for dynamic loading
+    "CovenantMetricsAdapter",
+    "CovenantMetricsService",
+]

ciris_adapters/ciris_covenant_metrics/adapter.py

@@ -0,0 +1,249 @@
+"""
+CIRIS Covenant Metrics Adapter.
+
+This adapter provides covenant compliance metrics collection for CIRISLens,
+reporting WBD (Wisdom-Based Deferral) events and PDMA decision events.
+
+CRITICAL: This adapter requires EXPLICIT opt-in via the setup wizard.
+No data is collected or sent without user consent.
+"""
+
+import asyncio
+import logging
+from datetime import datetime, timezone
+from typing import Any, List, Optional
+
+from ciris_engine.logic.adapters.base import Service
+from ciris_engine.logic.registries.base import Priority
+from ciris_engine.schemas.adapters import AdapterServiceRegistration
+from ciris_engine.schemas.runtime.adapter_management import AdapterConfig, RuntimeAdapterStatus
+from ciris_engine.schemas.runtime.enums import ServiceType
+from ciris_engine.schemas.types import JSONDict
+
+from .services import CovenantMetricsService
+
+logger = logging.getLogger(__name__)
+
+
+class CovenantMetricsAdapter(Service):
+    """
+    CIRIS Covenant Metrics Adapter.
+
+    This adapter:
+    1. Registers a WiseAuthority service to receive WBD events
+    2. Provides consent management for data collection
+    3. Batches and sends events to CIRISLens API
+
+    IMPORTANT: This adapter is NOT auto-loaded. It must be:
+    1. Explicitly added via --adapter ciris_covenant_metrics
+    2. Configured via the setup wizard with EXPLICIT consent
+
+    No data is sent until the user completes the consent flow.
+    """
+
+    def __init__(
+        self,
+        runtime: Any,
+        context: Optional[Any] = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize Covenant Metrics adapter.
+
+        Args:
+            runtime: CIRIS runtime instance
+            context: Optional runtime context
+            **kwargs: Additional configuration (may include adapter_config)
+        """
+        super().__init__(config=kwargs.get("adapter_config"))
+        self.runtime = runtime
+        self.context = context
+
+        # Extract config from kwargs
+        adapter_config = kwargs.get("adapter_config", {})
+
+        # Check consent state from config
+        self._consent_given = adapter_config.get("consent_given", False)
+        self._consent_timestamp = adapter_config.get("consent_timestamp")
+
+        if not self._consent_given:
+            logger.warning(
+                "CovenantMetricsAdapter initialized WITHOUT consent - "
+                "complete setup wizard to enable data collection"
+            )
+
+        # Create the underlying service with config
+        self.metrics_service = CovenantMetricsService(config=adapter_config)
+
+        # Set agent ID if available from runtime
+        if runtime and hasattr(runtime, "agent_id"):
+            self.metrics_service.set_agent_id(runtime.agent_id)
+        elif context and hasattr(context, "agent_id"):
+            self.metrics_service.set_agent_id(context.agent_id)
+
+        # Track adapter state
+        self._running = False
+        self._lifecycle_task: Optional[asyncio.Task[None]] = None
+        self._started_at: Optional[datetime] = None
+
+        logger.info(f"CovenantMetricsAdapter initialized (consent={self._consent_given})")
+
+    def get_services_to_register(self) -> List[AdapterServiceRegistration]:
+        """Get services provided by this adapter.
+
+        Returns:
+            List of service registrations for WiseAuthority bus
+        """
+        registrations = []
+
+        # Only register if consent is given
+        # This prevents the service from receiving events before consent
+        if self._consent_given:
+            registrations.append(
+                AdapterServiceRegistration(
+                    service_type=ServiceType.WISE_AUTHORITY,
+                    provider=self.metrics_service,
+                    priority=Priority.LOW,  # Low priority - observational only
+                    capabilities=[
+                        "send_deferral",  # Receive WBD events
+                        "covenant_metrics",
+                    ],
+                )
+            )
+            logger.info("Registered CovenantMetricsService with send_deferral capability")
+        else:
+            logger.warning(
+                "CovenantMetricsService NOT registered - consent required. " "Complete setup wizard to enable."
+            )
+
+        return registrations
+
+    async def start(self) -> None:
+        """Start the Covenant Metrics adapter."""
+        logger.info("Starting CovenantMetricsAdapter")
+
+        await self.metrics_service.start()
+
+        self._running = True
+        self._started_at = datetime.now(timezone.utc)
+
+        if self._consent_given:
+            logger.info("CovenantMetricsAdapter started with consent - collecting metrics")
+        else:
+            logger.info(
+                "CovenantMetricsAdapter started WITHOUT consent - " "no metrics will be collected until user consents"
+            )
+
+    async def stop(self) -> None:
+        """Stop the Covenant Metrics adapter."""
+        logger.info("Stopping CovenantMetricsAdapter")
+        self._running = False
+
+        # Cancel lifecycle task if running
+        if self._lifecycle_task and not self._lifecycle_task.done():
+            self._lifecycle_task.cancel()
+            try:
+                await self._lifecycle_task
+            except asyncio.CancelledError:
+                pass
+
+        await self.metrics_service.stop()
+
+        logger.info("CovenantMetricsAdapter stopped")
+
+    async def run_lifecycle(self, agent_task: Any) -> None:
+        """Run the adapter lifecycle.
+
+        For the covenant metrics adapter, we just wait for the agent task
+        to complete since it passively receives events.
+
+        Args:
+            agent_task: The main agent task (signals shutdown when complete)
+        """
+        logger.info("CovenantMetricsAdapter lifecycle started")
+        try:
+            await agent_task
+        except asyncio.CancelledError:
+            logger.info("CovenantMetricsAdapter lifecycle cancelled")
+        finally:
+            await self.stop()
+
+    def get_config(self) -> AdapterConfig:
+        """Get adapter configuration.
+
+        Returns:
+            Current adapter configuration
+        """
+        metrics = self.metrics_service.get_metrics()
+
+        return AdapterConfig(
+            adapter_type="ciris_covenant_metrics",
+            enabled=self._running and self._consent_given,
+            settings={
+                "consent_given": self._consent_given,
+                "consent_timestamp": self._consent_timestamp,
+                "events_received": metrics.get("events_received", 0),
+                "events_sent": metrics.get("events_sent", 0),
+                "events_failed": metrics.get("events_failed", 0),
+                "events_queued": metrics.get("events_queued", 0),
+            },
+        )
+
+    def get_status(self) -> RuntimeAdapterStatus:
+        """Get adapter status.
+
+        Returns:
+            Current adapter runtime status
+        """
+        metrics = self.metrics_service.get_metrics()
+
+        return RuntimeAdapterStatus(
+            adapter_id="ciris_covenant_metrics",
+            adapter_type="ciris_covenant_metrics",
+            is_running=self._running,
+            loaded_at=self._started_at or datetime.now(timezone.utc),
+            config_params=AdapterConfig(
+                adapter_type="ciris_covenant_metrics",
+                enabled=self._running and self._consent_given,
+                settings={
+                    "consent_given": self._consent_given,
+                    "consent_timestamp": self._consent_timestamp,
+                    "events_received": metrics.get("events_received", 0),
+                    "events_sent": metrics.get("events_sent", 0),
+                },
+            ),
+        )
+
+    # =========================================================================
+    # Consent Management API
+    # =========================================================================
+
+    def update_consent(self, consent_given: bool) -> None:
+        """Update consent state.
+
+        This is called by the setup wizard when consent is granted/revoked.
+
+        Args:
+            consent_given: Whether user has consented
+        """
+        self._consent_given = consent_given
+        self._consent_timestamp = datetime.now(timezone.utc).isoformat()
+
+        self.metrics_service.set_consent(consent_given, self._consent_timestamp)
+
+        if consent_given:
+            logger.info(f"Consent GRANTED for covenant metrics collection " f"at {self._consent_timestamp}")
+        else:
+            logger.info(f"Consent REVOKED for covenant metrics collection " f"at {self._consent_timestamp}")
+
+    def is_consent_given(self) -> bool:
+        """Check if consent has been given.
+
+        Returns:
+            True if user has explicitly consented
+        """
+        return bool(self._consent_given)
+
+
+# Export as Adapter for load_adapter() compatibility
+# This is the critical line that allows RuntimeAdapterManager to find the adapter
+Adapter = CovenantMetricsAdapter