Skip to content

insightitsGit/ChorusControl

BranchesTags

Repository files navigation

ChorusControl

Python 3.11+ License: Apache-2.0 Version CI

AI Operations Platform for the Prism / Chorus stack — mother control plane + lightweight fleet agents.
Govern, observe, and correct production AI fleets without putting Side 1 (billing) or phone-home inside the customer VPC.

# After v0.1.0 is on PyPI:
pip install "choruscontrol[server,agent]==0.1.0"

# Until then (or for tip-of-main):
# pip install "choruscontrol[server,agent] @ git+https://github.com/insightitsGit/ChorusControl.git@main"

set CHORUSCONTROL_DEMO_MODE=1
set CHORUSCONTROL_ADMIN_TOKEN=healthcare-demo-token
choruscontrol serve --host 127.0.0.1 --port 8443

Open http://127.0.0.1:8443/overview · API auth: Authorization: Bearer healthcare-demo-token

DEMO ≠ production truth. With CHORUSCONTROL_DEMO_MODE=1, missing Prism packs become NullAdapters and metrics/scores are labeled demo. Live pins report honest caps — we never fake Guard PASS, Shine PASS, or AI Score as world-true.

What is ChorusControl?

ChorusControl is the self-hosted ops layer above ChorusGraph, PrismGuard, PrismShine, PrismCortex, PrismRAG, and related products:

Layer Role
Mother FastAPI AI Ops UI + control APIs (Overview, Trace, Taxonomy, Cortex, Guard, Admin)
Fleet agent Background-only join / heartbeat / commands — zero hot-path latency on invoke/digest/recall
Correction cascade Cortex conflict → cache invalidate → Graph mark_revalidate → Shine consistency — one audited action
License Offline Ed25519 verify (Side 1 JWT) + optional ~14-day online revoke check

It is not an agent runtime (that’s ChorusGraph), not an injection firewall (PrismGuard), and not an answer verifier (PrismShine). It operates those products across a fleet.

When NOT to use ChorusControl

  • You only need a single-process agent graph → use ChorusGraph alone.
  • You only need jailbreak / WAF on ingress → use PrismGuard.
  • You only need answer grounding → use PrismShine.
  • You need Stripe / license issuance → that’s Side 1 (www.insightits.com), not this repo.
  • You need active-active multi-region mothers on day one → deferred; see doc/ChorusControl-Future-Mother-HA.md.

Why ChorusControl?

Pain ChorusControl answer
Many Prism nodes, no single ops surface Six-tab mother + Ops Assistant grounded in live telemetry
Fact correction doesn’t flush caches Correction cascade (invalidate + revalidate + audit)
Dashboards that lie about capabilities Honest caps + DEMO labels when NullAdapters are in use
Control plane on the request path Agent is background-only; hot path stays local
Air-gapped customers can’t phone home Offline license verify; online check is optional
“Who is serving Cortex for tenant X?” Fleet memory_endpoint + /cortex console

Customer path (after pip)

  1. Buy Enterprise (CONTROL) → paste CHORUSCONTROL_LICENSE_KEY.
  2. pip install "choruscontrol[server,agent]==0.1.0"
  3. choruscontrol serve → mother = dashboard + API at /overview (you host it; we do not).
  4. Optional: choruscontrol-agent on workers with a join token from Admin.

How enterprise licensing works

ChorusControl is self-hosted software. Insight IT Solutions sells the commercial license; you run the mother + agents in your VPC. Billing never lives inside the customer container.

  ┌─────────────────────────────┐         ┌──────────────────────────────────┐
  │  Side 1 — insightits.com    │         │  Side 2 — your VPC               │
  │  Account · Stripe · support │  JWT    │  Mother + fleet agents           │
  │  Issues signed license key  │ ──────► │  Verifies offline (Ed25519)      │
  │  Optional /validate (~14d)  │ ◄─opt─  │  Paste key in Admin → License    │
  └─────────────────────────────┘         └──────────────────────────────────┘

What you buy from us

The commercial product is ChorusControl Enterprise only (soft CTA CONTROL on insightits.com). There is no Starter SKU on the public catalog today.

  1. Request access via CONTROL / sign in at www.insightits.com.
  2. Complete Enterprise purchase / access (portal when Stripe checkout is live; sales / admin issue until then).
  3. Copy or download the license JWT from the portal (or email delivery).
  4. Install ChorusControl in your environment (DEMO_MODE=0).
  5. Paste the key into Admin → License or set CHORUSCONTROL_LICENSE_KEY.
  6. Mother verifies the signature offline — air-gap friendly. Connected installs may optionally call Side 1 about every 14 days only to pick up revocation (not required to boot).

You do not put Stripe keys, private signing keys, or the company website inside your ChorusControl image.

Pricing (commercial)

Product List price How to buy
ChorusControl Enterprise $24,000 / year Soft CTA CONTROL · pricing · portal /dashboard.html#choruscontrol

Issued Enterprise JWTs typically carry entitlements such as max_nodes / max_tenants and features trace.replay, guard.shadow, audit.export (exact claims come from Side 1 at issue time).

  • License JWT exp is typically ~90 days (or through the Stripe / contract period); renewals re-issue a new key.
  • After exp, Side 2 enters 14-day read-only grace (observe OK; mutations blocked), then fail-closed.
  • Air-gap / custom SLA deals are still Enterprise commercially — issued by sales / Agile Super Admin as needed (JWT may use a higher entitlement profile; not a separate public “Starter” plan).
  • Quotes and discounts are commercial — portal or sales.

Portal / support: www.insightits.com · support deep-link configurable via INSIGHTITS_SUPPORT_URL.
Contract detail: doc/Side1-insightits-com-Handoff.md.

Demo vs paid

Mode Who What you get
DEMO_MODE=1 Local eval / healthcare compose Auto demo JWT, NullAdapters OK, labeled demo
DEMO_MODE=0 + company JWT Paying / pilot customer Enforced tier, nodes, tenants, features; fail-closed without a valid key

Open-source install without a key is for evaluation with demo mode only — production enterprise use requires a license from Insight ITS.

Quick start (30 seconds)

1) Install

pip install "choruscontrol[server,agent]==0.1.0"

# Tip of main (pre-release / hotfix):
# pip install "choruscontrol[server,agent] @ git+https://github.com/insightitsGit/ChorusControl.git@main"

# Live Prism packs (public pins when available):
# pip install "choruscontrol[server,agent,prism]"

Editable clone:

git clone https://github.com/insightitsGit/ChorusControl.git
cd ChorusControl
pip install -e ".[server,agent,dev]"

2) Run mother (demo)

# Windows
set CHORUSCONTROL_DEMO_MODE=1
set CHORUSCONTROL_ADMIN_TOKEN=healthcare-demo-token
choruscontrol serve --host 127.0.0.1 --port 8443

# Linux / macOS
export CHORUSCONTROL_DEMO_MODE=1
export CHORUSCONTROL_ADMIN_TOKEN=healthcare-demo-token
choruscontrol serve --host 127.0.0.1 --port 8443
choruscontrol doctor --mode mother

3) Healthcare full-stack demo (recommended)

docker compose -f docker-compose.healthcare.yml up --build

Aurora Health scenario: mother + Postgres audit + clinical / pharmacy / edge agents + seeded traces/cascade.
UI: http://127.0.0.1:8443/overview · Bearer healthcare-demo-token
Details: doc/Healthcare-Demo.md.

4) Lightweight fleet agent

pip install "choruscontrol[agent] @ git+https://github.com/insightitsGit/ChorusControl.git@main"

set CHORUSCONTROL_MOTHER_URL=http://127.0.0.1:8443
set CHORUSCONTROL_JOIN_TOKEN=<from Admin → join token>
set CHORUSCONTROL_NODE_ID=worker-1
set CHORUSCONTROL_NODE_ROLE=GREEN
choruscontrol-agent

Or from app code (background only — never await on the hot path):

from choruscontrol.agent import attach_agent

# Schedules join/heartbeat/commands off the request path
attach_agent()

Features

Feature Description
Overview Fleet topology, health matrix, transparent AI Score, live pipeline viz
Trace Guard → Ledger → Shine wire; zero-token replay
Taxonomy Partition warm / reindex jobs; PrismRAG when pinned
Cortex PrismCortex activity, chunks, digest / recall / sleep
Guard studio Ingress profiles, shadow compare (feature-gated)
Admin License, doctor, tenants, stack licenses, SOC2 export pack, compliance scan
Ops Assistant Guard → ChorusGraph → Shine wire + grounded answers; gated execute
Cascade Conflict resolve → invalidate → mark_revalidate → fleet ACKs
License Offline Ed25519 + 14-day grace; optional Side 1 /validate
Exec / Eng modes Overview lenses for business vs engineering

Architecture

                    Customer VPC (Side 2)
┌──────────────────────────────────────────────────────────┐
│  Mother  :8443                                           │
│  UI tabs · /api/v1 · jobs · cascade · audit · SQLite/PG  │
└─────────────┬────────────────────────────────────────────┘
              │ HTTP join / heartbeat / commands (primary)
              │ Fabric optional
     ┌────────┼────────┬────────────┐
     ▼        ▼        ▼            ▼
  GREEN     BLUE    ORANGE      MEMORY/CORTEX
  worker    worker   edge         memory_endpoint
     │        │        │            │
     └────────┴────────┴────────────┘
        Prism packs local (Guard / Graph / Shine / RAG / Cortex)
        Agent = background only — no mother RTT on invoke

License issuance stays on Side 1. Mother verifies offline (and may optionally re-check revoke status ~every 14 days).

Install & extras

Extra Purpose
(none) Core libs
[server] Mother UI/API (FastAPI, Jinja, SQLite)
[agent] Fleet agent CLI
[postgres] Audit / control-plane dual-write (asyncpg)
[prism] Live pins: ChorusGraph, Guard, Shine, RAG, Cortex
[fabric] Optional CHORUS Fabric transport
[all] server + agent + postgres + prism
[dev] pytest, ruff

Packaging detail: doc/PACKAGING.md.

Production checklist

  1. CHORUSCONTROL_DEMO_MODE=0 — never ship demo NullAdapters unlabeled.
  2. Strong CHORUSCONTROL_ADMIN_TOKEN (≥16 chars; serve refuses weak defaults).
  3. Side 1 JWT in CHORUSCONTROL_LICENSE_KEY.
  4. Trust anchor — CHORUSCONTROL_LICENSE_PUBLIC_KEY_HEX from Side 1 ceremony --public (packaged PEM is a placeholder until you pin the live key).
  5. Optional: DATABASE_URL for Postgres durability; CHORUSCONTROL_LICENSE_ONLINE_CHECK=1 for revoke polling.

Full env list: doc/Azure-Mother-Env.md.

CLI

choruscontrol serve [--host 0.0.0.0] [--port 8443]
choruscontrol doctor --mode mother|agent|auto
choruscontrol audit-verify audit.jsonl --pubkey audit_public_key.pem
choruscontrol-agent
choruscontrol-keygen   # local/dev issuance helpers only — production keys are Side 1

Design decisions

Item Choice
Control transport HTTP primary; Fabric optional
Mother persistence SQLite default (+ WAL); Postgres via DATABASE_URL
License Offline verify + 14-day grace; optional online validate
Auth Admin bearer + optional OIDC
Observability Coexists with OTel — OTel watches; ChorusControl acts
Live Prism Pin floors when installed; else NullAdapters labeled DEMO

Side 1 (commercial portal)

Concern Where
Buy / renew / upgrade www.insightits.com
Stripe billing Side 1 only
License issuance (Ed25519 private key) Side 1 only
License verification This repo (Side 2)
Support tickets Side 1 support URL

Handoff contract: doc/Side1-insightits-com-Handoff.md.

Docs

Doc Contents
doc/ChorusControl-COMPLETE-DESIGN.md Full design authority
doc/Healthcare-Demo.md Aurora Health walkthrough
doc/ChorusControl-Enterprise-Depth.md Phase 3–6 depth shipped
doc/ChorusControl-Future-Mother-HA.md Deferred multi-region HA
doc/PACKAGING.md Wheels, extras, containers

Tests

pytest -q

Includes hot-path latency (S03), restart soak, publish-blocker regressions (license trust + fleet auth).

Publish (maintainers)

Full checklist: doc/PACKAGING.md (Trusted Publisher + tag v0.1.0).

git tag v0.1.0
git push origin v0.1.0
# GitHub Actions Publish: test → build → PyPI

License

Apache-2.0 — Insight IT Solutions LLC

About

ChorusControl — AI Operations Platform (mother + fleet agent) for the Prism / Chorus stack

Resources

Readme
License
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages