CIRISNode

Alignment & governance back-plane for the CIRIS ecosystem
Status: DEVELOPMENT — functional with stubbed integrations

---

1 Overview

CIRISNode is the remote utility that CIRISAgent clients will call for:

• Alignment benchmarking (Annex J HE-300 suite)
• Governance workflows (Event recording)

---

2 Core Responsibilities

1. Alignment API
   Runs HE-300 scenarios, returns signed benchmark reports.

2. WBD API
   Receives Wisdom-Based Deferral packages and streams replies.

3. Audit Anchoring Publishes daily SHA-256 digests of logs and benchmark results for transparency.

---

3 API Endpoints

All endpoints use the /api/v1 prefix unless noted otherwise. Most require a JWT obtained from the authentication endpoints.

General:

• GET /api/v1/health – Return service status, version, and public key.
• GET /metrics – Expose Prometheus style metrics.

Benchmarks:

• POST /api/v1/benchmarks/run – Launch an HE‑300 benchmark job.
• GET /api/v1/benchmarks/results/{job_id} – Fetch results for a benchmark job.
• POST /api/v1/simplebench/run – Start a SimpleBench job.
• POST /api/v1/simplebench/run-sync – Run a SimpleBench job synchronously.
• GET /api/v1/simplebench/results/{job_id} – Retrieve SimpleBench results.

Wisdom‑Based Deferral (WBD):

• POST /api/v1/wbd/submit – Submit a deferral request.
• GET /api/v1/wbd/tasks – List deferral tasks.
• POST /api/v1/wbd/tasks/{task_id}/resolve – Approve or reject a deferral.
• GET /api/v1/wbd/corrections – Poll for resolved tasks.

Agent Events:

• POST /api/v1/agent/events – Record agent events for auditing.
• GET /api/v1/agent/events – List recorded agent events.

LLM Utilities:

• GET /api/v1/ollama-models – List available local models.
• POST /api/v1/test-llm – Test connectivity to a language model provider.

Authentication:

• POST /auth/token – Obtain a JWT token.
• POST /auth/refresh – Refresh an existing token.

A2A Protocol (AgentBeats Compatible):

• GET /.well-known/agent.json – Agent Card discovery (no auth required).
• POST /a2a – JSON-RPC 2.0 endpoint for task management:
  • message/send – Start evaluation task or get scenarios.
  • tasks/get – Get task status and results.
  • tasks/list – List tasks with filtering.
  • tasks/cancel – Cancel a running task.
• GET /a2a/tasks/{task_id}/stream – SSE streaming for real-time task progress.

MCP Server (Model Context Protocol):

• GET /mcp/sse – SSE transport for MCP clients.
• POST /mcp/messages/ – MCP message endpoint.
• Tools available:
  • list_he300_scenarios – List available ethical scenarios.
  • run_he300_scenario – Evaluate a single scenario.
  • run_he300_batch – Parallel batch evaluation.
  • get_evaluation_report – Get signed evaluation report.
  • get_he300_categories – Get category information.
• Resources: he300://scenarios, he300://categories, he300://health

All responses are JSON and may include signatures in future releases.

---

6 Next Steps

• Draft OpenAPI specification for /api/v1/* endpoints.
• Design architecture and data-flow diagrams.
• Migrate existing EEE documentation into this new spec as code is developed.

---

7 License

This project is licensed under GNU AGPL v3.0 © 2025-2026 CIRIS AI Project

---

Deployment

See docs/deployment.md for the full production deployment guide, including Caddy/Nginx reverse proxy configuration, CORS setup, and troubleshooting.

Key point: CIRISNode handles CORS and security headers via FastAPI middleware. Your reverse proxy should not set its own Access-Control-* headers — doing so will override the application's CORS policy and break frontend requests. See the deployment guide for details.

---

Authentication

• JWT-based route protection added using FastAPI middleware
• Token issued via /auth/token
• All sensitive endpoints require Authorization: Bearer <token>
• Discord and Google logins are available via the dashboard. Configure DISCORD_CLIENT_ID, DISCORD_CLIENT_SECRET, GOOGLE_CLIENT_ID, and GOOGLE_CLIENT_SECRET in your environment.

Roles

• admin – full access including config updates
• wise_authority – read-only access to config
• discord_user – authenticated via Discord OAuth
• anonymous – default for new accounts

---

---

Ethical Pipeline (HE-300/EEE)

• Core HE-300 benchmark logic included
• Benchmark runs triggered via /api/v1/benchmarks/run
• Results are saved and accessible via /status/{id} and /results/{id}
• Placeholder inference logic is located in utils/inference.py

---

A2A Protocol & MCP Support

CIRISNode implements the A2A (Agent-to-Agent) Protocol and MCP (Model Context Protocol) for AgentBeats compatibility:

• Agent Card at /.well-known/agent.json for capability discovery
• JSON-RPC 2.0 endpoint at /a2a for task management
• SSE streaming for real-time progress updates during evaluation
• Parallel batch execution (6 concurrent batches of 50 scenarios)
• MCP tools for scenario listing, single/batch evaluation, and report retrieval
• Dual authentication supporting both JWT Bearer tokens and API keys

Running the Baseline Purple Agent

Test A2A connectivity with the included baseline purple agent:

# List available scenarios
python -m tests.purple_agent.run --url http://localhost:8000 --api-key YOUR_KEY --list-scenarios

# Run full HE-300 benchmark (300 scenarios)
python -m tests.purple_agent.run --url http://localhost:8000 --api-key YOUR_KEY --scenarios 300

# Run specific category only
python -m tests.purple_agent.run --url http://localhost:8000 --api-key YOUR_KEY --category commonsense

# Save results to file
python -m tests.purple_agent.run --url http://localhost:8000 --api-key YOUR_KEY --output results.json

---

Audit Anchoring

• A daily task (via APScheduler) publishes digests of benchmark activity
• SHA-256 hash + timestamp stored

---

Docker + CI/CD Support

• Dockerfile created to build and run app with uvicorn --workers
• Docker-based test container enabled (copies tests/ folder and runs pytest)
• GitHub Actions workflow (.github/workflows/test.yml) added to auto-run tests on push and pull requests
• .env file integrated via python-dotenv and used for secrets/config

---

Frontend Interface for EEE (Phase 1 Complete, Phase 3 Enhanced)

The Streamlit-based frontend and related files have been removed. All frontend functionality is deprecated in this repository.

---

🛠 Setup Instructions

This section provides detailed, step-by-step instructions to set up and run CIRISNode on your local machine or in a Docker container. Follow these steps carefully to ensure a successful setup.

Prerequisites

• Python 3.10+: Ensure Python 3.10 or higher is installed on your system. You can download it from python.org.
• Git: Required to clone the repository. Install from git-scm.com.
• Docker: Optional, for containerized setup. Install Docker Desktop from docker.com.
• Virtual Environment: Recommended for isolating project dependencies.
• Streamlit: Required for the frontend web application. Install via pip if running locally.

Step 1: Clone the Repository

git clone cirisai/cirisnode  # As per FSD
cd cirisnode

Step 2: Set Up a Virtual Environment

Create and activate a virtual environment to manage project dependencies.

python3 -m venv venv
source venv/bin/activate  # On Windows, use: venv\Scripts\activate

Step 3: Install Dependencies

Install the required Python packages listed in requirements.txt for the backend, and additional packages for the frontend.

pip install -r requirements.txt
pip install streamlit

Step 4: Configure Environment Variables

Create a .env file in the project root directory with the necessary environment variables. Use the following template as a starting point:

TODO: CLEAN UP ENV VARIABLES

Step 5: Run the Server Locally

To run the FastAPI server locally, you need to export the required environment variables and use uvicorn to start the server. Use the following command:

export ENVIRONMENT='dev' && export JWT_SECRET='temporary_secret' && uvicorn cirisnode.main:app --reload --port 8000

• ENVIRONMENT='dev': Sets the environment to development mode.
• JWT_SECRET='temporary_secret': Sets the secret key for JWT authentication.
• uvicorn cirisnode.main:app --reload --port 8000: Starts the FastAPI server with auto-reload enabled on port 8000.

Once the server is running:

• Access the health check endpoint at http://localhost:8000/api/v1/health to confirm the server is operational (should return {"status": "ok", "message": "Service is healthy", "timestamp": "2025-05-08T14:52:00Z"}).
• Explore the API documentation at http://localhost:8000/docs (available in dev or test environments).

Step 6: Run the Next.js Frontend Locally

The user interface lives in ui/. Start the development server with:

cd ui && npm run dev

The app will be available at http://localhost:3000.

Step 7: Run the Test Suite Locally

Ensure your environment is set to test by setting ENVIRONMENT=test in your .env file or by using environment variables in the command. Install test dependencies if not already installed, then run the tests.

export JWT_SECRET='temporary_secret' && pytest tests/ -v

• Tests cover health checks, JWT authentication, benchmark workflows, and more.
• Ensure JWT_SECRET is set to enable JWT authentication for protected routes during testing.

Step 8: Run Using Docker (Opt