# Eunomia

**Adeno Error Reporting, DevOps Pipeline, and Automated Reconciliation Service**

Portal: `https://eunomia.adeno.ltd`

Eunomia is a pseudo-public Adeno service that centralises error reporting and automated remediation across the Adeno platform and authorised external services.

```
Service / External Client
        │
        ▼  X-Eunomia-Key
┌────────────────────┐
│  Error Reporting   │  POST /eunomia/report
│  API               │
└────────┬───────────┘
         │ (background task)
         ▼
┌────────────────────┐
│  Triage Router     │  complexity score + novelty score
└────────┬───────────┘
         │
    ┌────┴────┐
    │         │
    ▼         ▼
 portal    reconcile
(manual)      │
              ▼
┌────────────────────┐
│  Reconciliation    │  Athena LLM → patch
│  Service           │  Uracil sandbox → test
└────────┬───────────┘
         │
         ▼
┌────────────────────┐
│  DeployCheck       │  CI / Security / Compliance gates
└────────────────────┘
```

## Components

### Error Reporting API

Registered clients submit errors via `POST /eunomia/report` authenticated with an `X-Eunomia-Key` header.

### Triage Router

Runs as a background task after each report is received.

**Complexity formula:**

$$t_{complexity} = \frac{\sum_{x=0}^{n}\!\left(t(x)_{time}\cdot\dfrac{t(x)_{priority}}{2}\right)}{n}$$

Where:

- $t(x)_{time}$ — log-scaled recency/duration weight clamped to `[0, MAX_TIME_WEIGHT]`
- $t(x)_{priority}$ — priority score 1–5 supplied by the submitting service
- $n$ — number of related error instances (current + similar historical)

**Routing:**

| Condition | Route |
|-----------|-------|
| `complexity ≥ HIGH_COMPLEXITY_THRESHOLD` **and** `novelty ≥ HIGH_NOVELTY_THRESHOLD` | `portal` (human review) |
| `complexity ≥ HIGH_COMPLEXITY_THRESHOLD × 1.5` | `portal` (high-impact override) |
| Otherwise | `reconcile` (automated) |

### Reconciliation Service

Calls Athena's development LLMs to generate a code patch, then boots a **Uracil** campaign to sandbox and test the patch before promotion.

### DeployCheck

Internal service that validates generated patches through three gates before deployment:

- **CI** — unit/integration tests (`DEPLOYCHECK_CI_CMD`)
- **Security** — SAST + dependency vulnerability scan (`DEPLOYCHECK_SECURITY_CMD`)
- **Compliance** — licence + policy checks (`DEPLOYCHECK_COMPLIANCE_CMD`)

Runner strategies: `mock` (dev) | `script` (shell commands) | `http` (external webhook).

### Web Portal

React SPA served at `/portal/` with pages for:

- **Dashboard** — live statistics
- **Reports** — full error report list with status management
- **Triage** — complexity/novelty scores and routing decisions
- **Reconciliations** — AI fix campaigns with patch viewer
- **DeployCheck** — gate logs per pipeline run
- **Clients** — service registration approval/revocation

## Quick start

1. Open the Eunomia portal and create or edit an EIDSpec.
2. For any zone using a FlashBack source, set `flashbackcredentials` to an exposed session token such as `cauth@"exposed-session-id"`.
3. Save the spec and trigger a deploy check or run.
4. Review the zone results and approve any gated steps.

### FlashBack credentials

The FlashBack source needs an approved credential string so Eunomia can read the live snapshot stream:

- Use the Exposed Sessions page in the Eunomia portal to mint a session token.
- Paste the token into the `flashbackcredentials` field in the EIDSpec editor.
- Admin users can use an approved session token for their own workspace without a separate billing path.

### Approval workflow

Some zones require approval before promotion. When a zone waits on approval, Eunomia pauses at the approval step until an admin confirms or rejects the run.

## Configuration

| Variable | Default | Description |
|---|---|---|
| `EUNOMIA_DATABASE_URL` | `sqlite:///data/eunomia.db` | SQLAlchemy URL |
| `EUNOMIA_ADMIN_EMAIL` | `administration@adeno.ltd` | Admin CAuth account |
| `EUNOMIA_INTERNAL_SECRET` | *(unset)* | Shared secret for internal service auth |
| `CAUTH_URL` | `http://cauth:5000` | CAuth service URL |
| `ATHENA_URL` | `http://athena:8001` | Athena LLM gateway |
| `URACIL_HOST_RUNTIME_URL` | `http://uracil:8005` | Uracil sandbox host |
| `DEPLOYCHECK_RUNNER` | `mock` | `mock` \| `script` \| `http` |
| `DEPLOYCHECK_CI_CMD` | *(unset)* | Shell command for CI gate |
| `DEPLOYCHECK_SECURITY_CMD` | *(unset)* | Shell command for security gate |
| `DEPLOYCHECK_COMPLIANCE_CMD` | *(unset)* | Shell command for compliance gate |
| `EUNOMIA_HIGH_COMPLEXITY_THRESHOLD` | `4.0` | Complexity threshold for portal escalation |
| `EUNOMIA_HIGH_NOVELTY_THRESHOLD` | `0.65` | Novelty threshold for portal escalation |
| `EUNOMIA_SEED_INTERNAL_CLIENTS` | `0` | Set `1` to auto-seed Adeno internal clients on startup |

## Running locally

```bash
# Backend
cd eunomia
pip install -r requirements.txt
mkdir -p data
EUNOMIA_SEED_INTERNAL_CLIENTS=1 uvicorn app.main:app --reload --port 8006

# Portal (separate terminal)
cd eunomia/portal && npm install && npm run dev
```

Interactive Swagger docs are available at `/eunomia/docs` on a running instance.

## Billing and trials

Adeno uses CAuth and Stripe for billing:

- New users can start with trial credits.
- Access can be reviewed manually before billing is activated.
- Once approved, the account can move from a trial state to a paid Stripe-backed plan.

## Need help?

Contact [hello@adeno.ltd](mailto:hello@adeno.ltd) for a walkthrough or help configuring a spec.