cortex-bus 0.4.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- cortex_bus-0.4.0/LICENSE +7 -0
- cortex_bus-0.4.0/PKG-INFO +197 -0
- cortex_bus-0.4.0/README.md +174 -0
- cortex_bus-0.4.0/conformance/__init__.py +0 -0
- cortex_bus-0.4.0/conformance/ablation_naive_prompt.py +15 -0
- cortex_bus-0.4.0/conformance/fixtures/routing_v1.json +533 -0
- cortex_bus-0.4.0/conformance/fixtures/routing_v2_injection.json +289 -0
- cortex_bus-0.4.0/conformance/fixtures/routing_v3_heldout.json +554 -0
- cortex_bus-0.4.0/conformance/run.py +413 -0
- cortex_bus-0.4.0/cortex_bus.egg-info/PKG-INFO +197 -0
- cortex_bus-0.4.0/cortex_bus.egg-info/SOURCES.txt +42 -0
- cortex_bus-0.4.0/cortex_bus.egg-info/dependency_links.txt +1 -0
- cortex_bus-0.4.0/cortex_bus.egg-info/entry_points.txt +4 -0
- cortex_bus-0.4.0/cortex_bus.egg-info/requires.txt +3 -0
- cortex_bus-0.4.0/cortex_bus.egg-info/top_level.txt +2 -0
- cortex_bus-0.4.0/cortexbus/__init__.py +5 -0
- cortex_bus-0.4.0/cortexbus/adapters/__init__.py +39 -0
- cortex_bus-0.4.0/cortexbus/adapters/anthropic.py +118 -0
- cortex_bus-0.4.0/cortexbus/adapters/base.py +289 -0
- cortex_bus-0.4.0/cortexbus/adapters/local.py +78 -0
- cortex_bus-0.4.0/cortexbus/adapters/ollama.py +114 -0
- cortex_bus-0.4.0/cortexbus/connectors.py +231 -0
- cortex_bus-0.4.0/cortexbus/core.py +1023 -0
- cortex_bus-0.4.0/cortexbus/guard.py +109 -0
- cortex_bus-0.4.0/cortexbus/http_api.py +345 -0
- cortex_bus-0.4.0/cortexbus/manifest.py +299 -0
- cortex_bus-0.4.0/cortexbus/mcp.py +224 -0
- cortex_bus-0.4.0/cortexbus/mediation.py +128 -0
- cortex_bus-0.4.0/cortexbus/runtime.py +153 -0
- cortex_bus-0.4.0/cortexbus/schema.py +103 -0
- cortex_bus-0.4.0/cortexbus/schemas/subscription.schema.json +57 -0
- cortex_bus-0.4.0/cortexbus/store.py +120 -0
- cortex_bus-0.4.0/cortexbus/streams.py +399 -0
- cortex_bus-0.4.0/pyproject.toml +42 -0
- cortex_bus-0.4.0/setup.cfg +4 -0
- cortex_bus-0.4.0/tests/test_adapters.py +663 -0
- cortex_bus-0.4.0/tests/test_capabilities.py +482 -0
- cortex_bus-0.4.0/tests/test_conformance.py +136 -0
- cortex_bus-0.4.0/tests/test_e2e_http.py +130 -0
- cortex_bus-0.4.0/tests/test_infra.py +611 -0
- cortex_bus-0.4.0/tests/test_kafka_live.py +72 -0
- cortex_bus-0.4.0/tests/test_live_example.py +103 -0
- cortex_bus-0.4.0/tests/test_mcp.py +110 -0
- cortex_bus-0.4.0/tests/test_streams.py +402 -0
cortex_bus-0.4.0/LICENSE
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
|
|
3
|
+
Copyright 2026 Cortex Bus contributors
|
|
4
|
+
|
|
5
|
+
Licensed under the Apache License, Version 2.0. Full text:
|
|
6
|
+
https://www.apache.org/licenses/LICENSE-2.0
|
|
7
|
+
(Replace this file with the full license text when you create the GitHub repo: Add file → Create new file → LICENSE → choose template.)
|
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: cortex-bus
|
|
3
|
+
Version: 0.4.0
|
|
4
|
+
Summary: Reference implementation of the Cortex Bus spec: semantic pub/sub with tiered (topic / embedding / LLM) routing
|
|
5
|
+
License: Apache-2.0
|
|
6
|
+
Project-URL: Homepage, https://github.com/cortex-bus/cortex-bus
|
|
7
|
+
Project-URL: Specification, https://github.com/cortex-bus/cortex-bus/blob/main/spec/SPEC.md
|
|
8
|
+
Project-URL: Issues, https://github.com/cortex-bus/cortex-bus/issues
|
|
9
|
+
Keywords: pubsub,message-bus,ai-agents,mcp,a2a,kafka,semantic-routing,llm
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: License :: OSI Approved :: Apache Software License
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
15
|
+
Classifier: Topic :: System :: Distributed Computing
|
|
16
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
17
|
+
Requires-Python: >=3.10
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
License-File: LICENSE
|
|
20
|
+
Provides-Extra: kafka
|
|
21
|
+
Requires-Dist: confluent-kafka>=2.3; extra == "kafka"
|
|
22
|
+
Dynamic: license-file
|
|
23
|
+
|
|
24
|
+
# Cortex Bus
|
|
25
|
+
|
|
26
|
+
**A bus that is an agent, on any transport.**
|
|
27
|
+
|
|
28
|
+
Cortex Bus is an open specification and reference implementation for an *agentic* publish/subscribe layer. It sits on top of the message transport you already run (Kafka, NATS, Redis Streams, SQS) and works with whichever model you choose (Claude, OpenAI, Gemini, Ollama, vLLM). On that base it adds what a conventional queue can't do: it understands what a message means.
|
|
29
|
+
|
|
30
|
+
| Conventional broker | Cortex Bus |
|
|
31
|
+
|---|---|
|
|
32
|
+
| String topics | Semantic subscriptions: subscribe by meaning |
|
|
33
|
+
| Payload delivered as-is | Schema mediation: each subscriber gets its own contract |
|
|
34
|
+
| Dedupe by message ID | Semantic dedupe: 40 alerts about one incident become 1 |
|
|
35
|
+
| Static priority | Reasoned urgency, with a recorded rationale |
|
|
36
|
+
| Slow consumer → lag or drop | Backlog summarization: a digest instead of a loss |
|
|
37
|
+
| Dead-letter queue | Self-healing DLQ: diagnose, repair, retry or escalate |
|
|
38
|
+
| Replay the raw log | Briefings: "catch me up on order 123 since Monday" |
|
|
39
|
+
| One reply | Consensus fan-in: ask N agents, reconcile the answers |
|
|
40
|
+
| Per-topic ACLs | Per-subscriber redaction by clearance |
|
|
41
|
+
| Opaque routing | Every decision audited and replayable |
|
|
42
|
+
|
|
43
|
+
## Design principles
|
|
44
|
+
|
|
45
|
+
1. **Deterministic first.** Exact topic match runs in microseconds, embeddings in milliseconds, and the LLM runs only when the lower tiers are unsure.
|
|
46
|
+
2. **Agnostic by contract.** Transport and model are adapters behind small interfaces.
|
|
47
|
+
3. **Explainable.** Every routing, transform or drop decision writes an audit record with its reason, model, prompt hash and input hash.
|
|
48
|
+
4. **Safe by default.** Redaction and clearance are checked before any model sees a payload. Any topic can be declared `strict`, which means no model in its path.
|
|
49
|
+
|
|
50
|
+
## Repository layout
|
|
51
|
+
|
|
52
|
+
```
|
|
53
|
+
spec/SPEC.md The specification (v0.1, draft)
|
|
54
|
+
schemas/ JSON Schemas: envelope, subscription, audit record
|
|
55
|
+
cortexbus/ Reference implementation (Python ≥3.10, standard library only)
|
|
56
|
+
core.py The bus: tiered routing, delivery pipeline, briefings, fan-in, audit + replay
|
|
57
|
+
guard.py Tier 1 injection guard: phrase patterns and a model screen
|
|
58
|
+
mediation.py Schema mediation, transform promotion, DLQ repair proposals
|
|
59
|
+
schema.py Small JSON Schema validator (stdlib)
|
|
60
|
+
mcp.py MCP server over stdio (SPEC §9.1)
|
|
61
|
+
http_api.py HTTP tool API, A2A agent (SPEC §9.2), SSE / WebSocket endpoints, live viewer
|
|
62
|
+
streams.py Server-Sent Events and WebSocket (RFC 6455) delivery, stdlib
|
|
63
|
+
store.py Durable state in SQLite
|
|
64
|
+
connectors.py Sources and sinks: JSON Lines files, webhooks, Kafka (optional client)
|
|
65
|
+
manifest.py Manifest loading: JSON or YAML (stdlib YAML subset), validated
|
|
66
|
+
runtime.py Shared server start-up; in-process, HTTP and A2A fan-in responders
|
|
67
|
+
adapters/ Embedder / reasoner adapters: local, Ollama, Claude
|
|
68
|
+
conformance/ Routing conformance suite: fixtures, runner, reports, RESULTS.md
|
|
69
|
+
tests/ Unit tests (mocked HTTP) and an end-to-end test over local sockets
|
|
70
|
+
examples/subscriptions/ Subscription manifests (YAML)
|
|
71
|
+
examples/envelopes/ Sample message envelopes
|
|
72
|
+
examples/python/quickstart.py Single-file offline demo (the original spec sketch)
|
|
73
|
+
examples/python/capabilities.py Tour of the package's capabilities (offline, or --real)
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## Install
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
pip install cortex-bus # the package; import it as cortexbus
|
|
80
|
+
pip install "cortex-bus[kafka]" # adds the Kafka connectors
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
The spec is [spec/SPEC.md](spec/SPEC.md). The package needs Python 3.10 or later and has no required dependencies.
|
|
84
|
+
|
|
85
|
+
## Quickstart
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
python3 examples/python/quickstart.py # single-file offline demo
|
|
89
|
+
python3 examples/python/capabilities.py # capabilities tour on the package (add --real for Ollama + Claude)
|
|
90
|
+
python3 -m conformance.run --calibrate # offline routing benchmark (no dependencies)
|
|
91
|
+
python3 -m unittest discover -s tests # tests, no network needed
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
The demo runs fully offline. It uses an in-memory transport, a bag-of-words embedder and a rule-based stand-in for the LLM, and shows tiered routing, schema mediation, redaction, semantic dedupe, backlog digests and the audit log.
|
|
95
|
+
|
|
96
|
+
## With real models
|
|
97
|
+
|
|
98
|
+
The embedder (Tier 1) and the reasoner (Tier 2 judge) are separate roles, so any embedder pairs with any reasoner. Ollama provides embeddings and an optional local judge. Claude (Anthropic Messages API) provides the judge, schema mediation and summaries. Models only ever see the `pii:none` view of a payload, wrapped in `<message>` tags as data.
|
|
99
|
+
|
|
100
|
+
```python
|
|
101
|
+
from cortexbus import CortexBus, Subscription
|
|
102
|
+
from cortexbus.adapters import build_embedder, build_reasoner
|
|
103
|
+
|
|
104
|
+
bus = CortexBus(build_embedder("ollama"), build_reasoner("claude"), delta=0.05)
|
|
105
|
+
bus.subscribe(Subscription("fraud-agent", intent="possible account takeover or fraudulent payment activity", threshold=0.58))
|
|
106
|
+
print(bus.publish({"id": "m1", "topic": "payments.events", "data": {"text": "New device, password reset, then a $4,800 transfer"}}))
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Setup: `ollama pull nomic-embed-text` (and `ollama pull llama3.2` for a local judge), and `export ANTHROPIC_API_KEY=...` for Claude. Optional settings: `OLLAMA_HOST`, `CORTEX_CLAUDE_MODEL` (default `claude-haiku-5-5`), `CORTEX_OLLAMA_MODEL`, `CORTEX_OLLAMA_EMBED_MODEL`. Thresholds depend on the embedder's similarity scale, so calibrate them with `python -m conformance.run --embedder ollama --calibrate`. Measured routing quality per model combination is in [conformance/RESULTS.md](conformance/RESULTS.md).
|
|
110
|
+
|
|
111
|
+
## Capabilities
|
|
112
|
+
|
|
113
|
+
Everything below is in `cortexbus` and covered by offline tests; `examples/python/capabilities.py --real` runs it against Ollama + Claude.
|
|
114
|
+
|
|
115
|
+
| SPEC | Capability | API |
|
|
116
|
+
|---|---|---|
|
|
117
|
+
| §5 | Tiered routing (topic → embedding → LLM judge), Tier 1 injection guard, per-subscriber and per-publisher token budgets, `max_tier_1` policy | `publish(env)` |
|
|
118
|
+
| §6.2 | Schema mediation: model transform on the `pii:none` view, PII re-attached per clearance, JSON Schema validation, transform promotion | `Subscription(schema=…, language=…, detail=…)` |
|
|
119
|
+
| §6.3 | Semantic dedupe within a window, per trace root unless `cross_trace` | `dedupe_threshold`, `dedupe_window` |
|
|
120
|
+
| §6.4 | Digests (`mode: digest`, `digest_window`, `max_lag`) and overflow `summarize` / `drop_oldest` / `block` | `consume(sub)`, `lag(sub)`, `flush_digests()` |
|
|
121
|
+
| §6.5 | Self-healing DLQ: classify, propose a repair, retry once, escalate; strict messages never repaired | `dlq_list()`, `dlq_resolve(id, action)` |
|
|
122
|
+
| §6.6 | Briefings with citations | `brief(query, since, scope)` |
|
|
123
|
+
| §6.7 | Consensus fan-in with quorum, timeout, model or majority reconciliation | `register_responder()`, `ask()` |
|
|
124
|
+
| §8 | Audit record per decision, explain and replay | `explain(id)`, `replay(id)` |
|
|
125
|
+
| §9.1 | MCP server (stdio) | `python -m cortexbus.mcp --embedder ollama --reasoner claude --manifest subs.yaml` |
|
|
126
|
+
| §9.2 | A2A agent and HTTP tool API; skills mirror the MCP tools | `python -m cortexbus.http_api --port 8765 --manifest subs.yaml` |
|
|
127
|
+
|
|
128
|
+
## Running it as a service
|
|
129
|
+
|
|
130
|
+
Both servers take the same flags:
|
|
131
|
+
|
|
132
|
+
- **Manifests:** `--manifest` (repeatable) reads `.yaml`, `.yml` or `.json`: one manifest, a list, or several YAML documents. YAML is parsed by a small standard-library reader that covers what manifests use; anchors, aliases and tags are rejected with a line number. Every manifest is validated against `schemas/subscription.schema.json`, and a `contract.schema` path is resolved next to the manifest file.
|
|
133
|
+
- **Durable state:** `--store bus.db` keeps subscriptions, message history, the audit log, the DLQ, undelivered queues and open digests in SQLite, written in one transaction per operation. After a restart, `explain`, `replay` and briefings still work on old messages. Consumer handlers (code) are not stored, so re-attach them.
|
|
134
|
+
- **Fan-in across processes:** `--responder` (repeatable) takes `name=module:function` (in-process), `name=http(s)://…` (POST `{question, request}` and get back `{answer}`) or `name=a2a+http(s)://…` (an A2A agent, called with `message/send`). With `--allow-register`, clients can add remote responders at runtime through the `register_responder` tool. The bus then POSTs to URLs those clients choose, so this is off by default.
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
python -m cortexbus.http_api --embedder ollama --reasoner claude --store bus.db \
|
|
138
|
+
--manifest examples/subscriptions/ops-inbox.yaml --responder risk=a2a+http://127.0.0.1:9001/a2a
|
|
139
|
+
curl -s localhost:8765/.well-known/agent-card.json # A2A agent card
|
|
140
|
+
curl -s localhost:8765/publish -d '{"topic":"ops.checkout","data":{"text":"checkout 500s in eu-west"}}'
|
|
141
|
+
curl -s localhost:8765/tools/consume -d '{"subscriber":"ops-inbox"}'
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
### Live delivery: Server-Sent Events and WebSockets
|
|
145
|
+
|
|
146
|
+
A subscriber can take its deliveries as a live stream instead of polling `consume`. Routed messages, digests and mediated payloads arrive as they happen. Anything delivered while nobody was connected waits in the queue (and in the store, with `--store`) and is sent on connect.
|
|
147
|
+
|
|
148
|
+
- `GET /stream/<subscriber>`: Server-Sent Events. Each delivery is an `event: message` or `event: digest` whose data is the envelope as JSON. Any browser's `EventSource` works.
|
|
149
|
+
- `GET /ws`: a WebSocket that works both ways. Send `{"op":"subscribe","manifest":{…},"ephemeral":true}` to create a subscription for this socket only, removed when it closes, or `{"op":"subscribe","subscriber":"name"}` to attach to an existing one. Deliveries are pushed as `{"type":"message"|"digest","subscriber":…,"envelope":…}`. The same socket can `publish` and `call` any tool, such as `brief`.
|
|
150
|
+
- `GET /ui`: a small page that watches any subscriber's SSE stream. It works on a phone too.
|
|
151
|
+
|
|
152
|
+
```bash
|
|
153
|
+
curl -N localhost:8765/stream/ops-inbox # SSE in a terminal
|
|
154
|
+
```
|
|
155
|
+
```js
|
|
156
|
+
const ws = new WebSocket("ws://localhost:8765/ws");
|
|
157
|
+
ws.onopen = () => ws.send(JSON.stringify({op: "subscribe", ephemeral: true,
|
|
158
|
+
manifest: {subscriber: "my-tab", match: {intent: "customer-facing outages", threshold: 0.6}}}));
|
|
159
|
+
ws.onmessage = e => console.log(JSON.parse(e.data));
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
Both endpoints implement the SSE and WebSocket bindings in [SPEC §9.3](spec/SPEC.md) (message shapes: `schemas/stream.schema.json`; WebSocket subprotocol `cortex.v0.2`). Streams are event-driven: the bus announces each delivery, so an idle stream does no work, and a write that fails puts the unsent items back at the front of the queue. A connected stream is that subscriber's consumer, so each subscriber allows one live connection at a time; a second one gets 409. For fan-out to many viewers, give each viewer its own (ephemeral) subscription. Each one then also gets its own contract, clearance and digest settings. Both stream types use only the standard library.
|
|
163
|
+
|
|
164
|
+
The HTTP server listens on 127.0.0.1. To bind any other address you must set `--token` (or `CORTEX_BUS_TOKEN`), and every POST and stream then needs `Authorization: Bearer <token>`. Streams also accept `?token=`, because browsers can't set headers on `EventSource` or `WebSocket`. Requests whose `Origin` is another site are refused, so a web page you visit can't drive a bus running on your machine. A2A clients send `message/send`, name the skill in `message.metadata.skill` or in a data part `{skill, arguments}`, and get back a message with one data part. A text-only message runs a briefing.
|
|
165
|
+
|
|
166
|
+
**Connectors** (`cortexbus.connectors`) connect the bus to message systems. A source is any iterable of envelopes, and `pump(source, bus)` publishes them. A sink is a callable you attach as a subscription's `handler`, so a failed hand-off goes to the self-healing DLQ like any consumer error.
|
|
167
|
+
|
|
168
|
+
| Connector | Needs | Notes |
|
|
169
|
+
|---|---|---|
|
|
170
|
+
| `JsonlSource(path, follow=True)` / `JsonlSink(path)` | stdlib | tails a file like `tail -f`; bad lines are skipped and reported |
|
|
171
|
+
| `WebhookSink(url)` | stdlib | non-2xx or network error → DLQ `consumer_error`; timeout → `timeout` |
|
|
172
|
+
| HTTP `POST /publish` | stdlib | for producers and webhooks; any JSON value is wrapped as `data` |
|
|
173
|
+
| `KafkaSource(topics, …)` / `KafkaSink(topic, …)` | `confluent-kafka` or `kafka-python` | JSON records; offsets committed after each publish (at-least-once); produce waits for the broker's ack |
|
|
174
|
+
|
|
175
|
+
```python
|
|
176
|
+
from cortexbus.connectors import KafkaSource, KafkaSink, pump
|
|
177
|
+
bus.subscribe(Subscription("fraud-out", intent="account takeover", threshold=0.6, handler=KafkaSink("fraud.alerts")))
|
|
178
|
+
pump(KafkaSource(["payments.events"], bootstrap_servers="localhost:9092"), bus)
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
The Kafka connectors are unit-tested against an in-memory fake of the `confluent-kafka` API. `tests/test_kafka_live.py` also runs them against a real broker when credentials are present (it passed on Aiven's free tier, and CI skips it). `examples/python/kafka_live.py` streams live Wikipedia edits through Kafka into the bus, and `serve` shows the routed feed in a browser. Results are in [conformance/RESULTS.md](conformance/RESULTS.md#live-wikipedia-edits-through-a-managed-kafka-2026-11-19).
|
|
182
|
+
|
|
183
|
+
## Conformance levels
|
|
184
|
+
|
|
185
|
+
| Level | Name | Requires |
|
|
186
|
+
|---|---|---|
|
|
187
|
+
| L0 | Classic | Envelope, exact topics, audit |
|
|
188
|
+
| L1 | Semantic | L0 + embedding tier, semantic subscriptions, dedupe |
|
|
189
|
+
| L2 | Agentic | L1 + LLM tier, schema mediation, summarization, self-healing DLQ, briefings, fan-in |
|
|
190
|
+
|
|
191
|
+
## Status
|
|
192
|
+
|
|
193
|
+
Draft spec v0.1. The reference implementation covers every capability in L0–L2 (table above), plus the optional A2A interface (§9.2). State is in memory, or in SQLite with `--store`. One bus process owns a store: there is no clustering or replication. Connectors cover files, webhooks, HTTP and Kafka. NATS, Redis Streams and SQS fit the same source/sink shape but are not written yet. Feedback is welcome through issues and RFC pull requests against `spec/`.
|
|
194
|
+
|
|
195
|
+
## License
|
|
196
|
+
|
|
197
|
+
Apache-2.0
|
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
# Cortex Bus
|
|
2
|
+
|
|
3
|
+
**A bus that is an agent, on any transport.**
|
|
4
|
+
|
|
5
|
+
Cortex Bus is an open specification and reference implementation for an *agentic* publish/subscribe layer. It sits on top of the message transport you already run (Kafka, NATS, Redis Streams, SQS) and works with whichever model you choose (Claude, OpenAI, Gemini, Ollama, vLLM). On that base it adds what a conventional queue can't do: it understands what a message means.
|
|
6
|
+
|
|
7
|
+
| Conventional broker | Cortex Bus |
|
|
8
|
+
|---|---|
|
|
9
|
+
| String topics | Semantic subscriptions: subscribe by meaning |
|
|
10
|
+
| Payload delivered as-is | Schema mediation: each subscriber gets its own contract |
|
|
11
|
+
| Dedupe by message ID | Semantic dedupe: 40 alerts about one incident become 1 |
|
|
12
|
+
| Static priority | Reasoned urgency, with a recorded rationale |
|
|
13
|
+
| Slow consumer → lag or drop | Backlog summarization: a digest instead of a loss |
|
|
14
|
+
| Dead-letter queue | Self-healing DLQ: diagnose, repair, retry or escalate |
|
|
15
|
+
| Replay the raw log | Briefings: "catch me up on order 123 since Monday" |
|
|
16
|
+
| One reply | Consensus fan-in: ask N agents, reconcile the answers |
|
|
17
|
+
| Per-topic ACLs | Per-subscriber redaction by clearance |
|
|
18
|
+
| Opaque routing | Every decision audited and replayable |
|
|
19
|
+
|
|
20
|
+
## Design principles
|
|
21
|
+
|
|
22
|
+
1. **Deterministic first.** Exact topic match runs in microseconds, embeddings in milliseconds, and the LLM runs only when the lower tiers are unsure.
|
|
23
|
+
2. **Agnostic by contract.** Transport and model are adapters behind small interfaces.
|
|
24
|
+
3. **Explainable.** Every routing, transform or drop decision writes an audit record with its reason, model, prompt hash and input hash.
|
|
25
|
+
4. **Safe by default.** Redaction and clearance are checked before any model sees a payload. Any topic can be declared `strict`, which means no model in its path.
|
|
26
|
+
|
|
27
|
+
## Repository layout
|
|
28
|
+
|
|
29
|
+
```
|
|
30
|
+
spec/SPEC.md The specification (v0.1, draft)
|
|
31
|
+
schemas/ JSON Schemas: envelope, subscription, audit record
|
|
32
|
+
cortexbus/ Reference implementation (Python ≥3.10, standard library only)
|
|
33
|
+
core.py The bus: tiered routing, delivery pipeline, briefings, fan-in, audit + replay
|
|
34
|
+
guard.py Tier 1 injection guard: phrase patterns and a model screen
|
|
35
|
+
mediation.py Schema mediation, transform promotion, DLQ repair proposals
|
|
36
|
+
schema.py Small JSON Schema validator (stdlib)
|
|
37
|
+
mcp.py MCP server over stdio (SPEC §9.1)
|
|
38
|
+
http_api.py HTTP tool API, A2A agent (SPEC §9.2), SSE / WebSocket endpoints, live viewer
|
|
39
|
+
streams.py Server-Sent Events and WebSocket (RFC 6455) delivery, stdlib
|
|
40
|
+
store.py Durable state in SQLite
|
|
41
|
+
connectors.py Sources and sinks: JSON Lines files, webhooks, Kafka (optional client)
|
|
42
|
+
manifest.py Manifest loading: JSON or YAML (stdlib YAML subset), validated
|
|
43
|
+
runtime.py Shared server start-up; in-process, HTTP and A2A fan-in responders
|
|
44
|
+
adapters/ Embedder / reasoner adapters: local, Ollama, Claude
|
|
45
|
+
conformance/ Routing conformance suite: fixtures, runner, reports, RESULTS.md
|
|
46
|
+
tests/ Unit tests (mocked HTTP) and an end-to-end test over local sockets
|
|
47
|
+
examples/subscriptions/ Subscription manifests (YAML)
|
|
48
|
+
examples/envelopes/ Sample message envelopes
|
|
49
|
+
examples/python/quickstart.py Single-file offline demo (the original spec sketch)
|
|
50
|
+
examples/python/capabilities.py Tour of the package's capabilities (offline, or --real)
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Install
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
pip install cortex-bus # the package; import it as cortexbus
|
|
57
|
+
pip install "cortex-bus[kafka]" # adds the Kafka connectors
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
The spec is [spec/SPEC.md](spec/SPEC.md). The package needs Python 3.10 or later and has no required dependencies.
|
|
61
|
+
|
|
62
|
+
## Quickstart
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
python3 examples/python/quickstart.py # single-file offline demo
|
|
66
|
+
python3 examples/python/capabilities.py # capabilities tour on the package (add --real for Ollama + Claude)
|
|
67
|
+
python3 -m conformance.run --calibrate # offline routing benchmark (no dependencies)
|
|
68
|
+
python3 -m unittest discover -s tests # tests, no network needed
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
The demo runs fully offline. It uses an in-memory transport, a bag-of-words embedder and a rule-based stand-in for the LLM, and shows tiered routing, schema mediation, redaction, semantic dedupe, backlog digests and the audit log.
|
|
72
|
+
|
|
73
|
+
## With real models
|
|
74
|
+
|
|
75
|
+
The embedder (Tier 1) and the reasoner (Tier 2 judge) are separate roles, so any embedder pairs with any reasoner. Ollama provides embeddings and an optional local judge. Claude (Anthropic Messages API) provides the judge, schema mediation and summaries. Models only ever see the `pii:none` view of a payload, wrapped in `<message>` tags as data.
|
|
76
|
+
|
|
77
|
+
```python
|
|
78
|
+
from cortexbus import CortexBus, Subscription
|
|
79
|
+
from cortexbus.adapters import build_embedder, build_reasoner
|
|
80
|
+
|
|
81
|
+
bus = CortexBus(build_embedder("ollama"), build_reasoner("claude"), delta=0.05)
|
|
82
|
+
bus.subscribe(Subscription("fraud-agent", intent="possible account takeover or fraudulent payment activity", threshold=0.58))
|
|
83
|
+
print(bus.publish({"id": "m1", "topic": "payments.events", "data": {"text": "New device, password reset, then a $4,800 transfer"}}))
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Setup: `ollama pull nomic-embed-text` (and `ollama pull llama3.2` for a local judge), and `export ANTHROPIC_API_KEY=...` for Claude. Optional settings: `OLLAMA_HOST`, `CORTEX_CLAUDE_MODEL` (default `claude-haiku-5-5`), `CORTEX_OLLAMA_MODEL`, `CORTEX_OLLAMA_EMBED_MODEL`. Thresholds depend on the embedder's similarity scale, so calibrate them with `python -m conformance.run --embedder ollama --calibrate`. Measured routing quality per model combination is in [conformance/RESULTS.md](conformance/RESULTS.md).
|
|
87
|
+
|
|
88
|
+
## Capabilities
|
|
89
|
+
|
|
90
|
+
Everything below is in `cortexbus` and covered by offline tests; `examples/python/capabilities.py --real` runs it against Ollama + Claude.
|
|
91
|
+
|
|
92
|
+
| SPEC | Capability | API |
|
|
93
|
+
|---|---|---|
|
|
94
|
+
| §5 | Tiered routing (topic → embedding → LLM judge), Tier 1 injection guard, per-subscriber and per-publisher token budgets, `max_tier_1` policy | `publish(env)` |
|
|
95
|
+
| §6.2 | Schema mediation: model transform on the `pii:none` view, PII re-attached per clearance, JSON Schema validation, transform promotion | `Subscription(schema=…, language=…, detail=…)` |
|
|
96
|
+
| §6.3 | Semantic dedupe within a window, per trace root unless `cross_trace` | `dedupe_threshold`, `dedupe_window` |
|
|
97
|
+
| §6.4 | Digests (`mode: digest`, `digest_window`, `max_lag`) and overflow `summarize` / `drop_oldest` / `block` | `consume(sub)`, `lag(sub)`, `flush_digests()` |
|
|
98
|
+
| §6.5 | Self-healing DLQ: classify, propose a repair, retry once, escalate; strict messages never repaired | `dlq_list()`, `dlq_resolve(id, action)` |
|
|
99
|
+
| §6.6 | Briefings with citations | `brief(query, since, scope)` |
|
|
100
|
+
| §6.7 | Consensus fan-in with quorum, timeout, model or majority reconciliation | `register_responder()`, `ask()` |
|
|
101
|
+
| §8 | Audit record per decision, explain and replay | `explain(id)`, `replay(id)` |
|
|
102
|
+
| §9.1 | MCP server (stdio) | `python -m cortexbus.mcp --embedder ollama --reasoner claude --manifest subs.yaml` |
|
|
103
|
+
| §9.2 | A2A agent and HTTP tool API; skills mirror the MCP tools | `python -m cortexbus.http_api --port 8765 --manifest subs.yaml` |
|
|
104
|
+
|
|
105
|
+
## Running it as a service
|
|
106
|
+
|
|
107
|
+
Both servers take the same flags:
|
|
108
|
+
|
|
109
|
+
- **Manifests:** `--manifest` (repeatable) reads `.yaml`, `.yml` or `.json`: one manifest, a list, or several YAML documents. YAML is parsed by a small standard-library reader that covers what manifests use; anchors, aliases and tags are rejected with a line number. Every manifest is validated against `schemas/subscription.schema.json`, and a `contract.schema` path is resolved next to the manifest file.
|
|
110
|
+
- **Durable state:** `--store bus.db` keeps subscriptions, message history, the audit log, the DLQ, undelivered queues and open digests in SQLite, written in one transaction per operation. After a restart, `explain`, `replay` and briefings still work on old messages. Consumer handlers (code) are not stored, so re-attach them.
|
|
111
|
+
- **Fan-in across processes:** `--responder` (repeatable) takes `name=module:function` (in-process), `name=http(s)://…` (POST `{question, request}` and get back `{answer}`) or `name=a2a+http(s)://…` (an A2A agent, called with `message/send`). With `--allow-register`, clients can add remote responders at runtime through the `register_responder` tool. The bus then POSTs to URLs those clients choose, so this is off by default.
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
python -m cortexbus.http_api --embedder ollama --reasoner claude --store bus.db \
|
|
115
|
+
--manifest examples/subscriptions/ops-inbox.yaml --responder risk=a2a+http://127.0.0.1:9001/a2a
|
|
116
|
+
curl -s localhost:8765/.well-known/agent-card.json # A2A agent card
|
|
117
|
+
curl -s localhost:8765/publish -d '{"topic":"ops.checkout","data":{"text":"checkout 500s in eu-west"}}'
|
|
118
|
+
curl -s localhost:8765/tools/consume -d '{"subscriber":"ops-inbox"}'
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
### Live delivery: Server-Sent Events and WebSockets
|
|
122
|
+
|
|
123
|
+
A subscriber can take its deliveries as a live stream instead of polling `consume`. Routed messages, digests and mediated payloads arrive as they happen. Anything delivered while nobody was connected waits in the queue (and in the store, with `--store`) and is sent on connect.
|
|
124
|
+
|
|
125
|
+
- `GET /stream/<subscriber>`: Server-Sent Events. Each delivery is an `event: message` or `event: digest` whose data is the envelope as JSON. Any browser's `EventSource` works.
|
|
126
|
+
- `GET /ws`: a WebSocket that works both ways. Send `{"op":"subscribe","manifest":{…},"ephemeral":true}` to create a subscription for this socket only, removed when it closes, or `{"op":"subscribe","subscriber":"name"}` to attach to an existing one. Deliveries are pushed as `{"type":"message"|"digest","subscriber":…,"envelope":…}`. The same socket can `publish` and `call` any tool, such as `brief`.
|
|
127
|
+
- `GET /ui`: a small page that watches any subscriber's SSE stream. It works on a phone too.
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
curl -N localhost:8765/stream/ops-inbox # SSE in a terminal
|
|
131
|
+
```
|
|
132
|
+
```js
|
|
133
|
+
const ws = new WebSocket("ws://localhost:8765/ws");
|
|
134
|
+
ws.onopen = () => ws.send(JSON.stringify({op: "subscribe", ephemeral: true,
|
|
135
|
+
manifest: {subscriber: "my-tab", match: {intent: "customer-facing outages", threshold: 0.6}}}));
|
|
136
|
+
ws.onmessage = e => console.log(JSON.parse(e.data));
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Both endpoints implement the SSE and WebSocket bindings in [SPEC §9.3](spec/SPEC.md) (message shapes: `schemas/stream.schema.json`; WebSocket subprotocol `cortex.v0.2`). Streams are event-driven: the bus announces each delivery, so an idle stream does no work, and a write that fails puts the unsent items back at the front of the queue. A connected stream is that subscriber's consumer, so each subscriber allows one live connection at a time; a second one gets 409. For fan-out to many viewers, give each viewer its own (ephemeral) subscription. Each one then also gets its own contract, clearance and digest settings. Both stream types use only the standard library.
|
|
140
|
+
|
|
141
|
+
The HTTP server listens on 127.0.0.1. To bind any other address you must set `--token` (or `CORTEX_BUS_TOKEN`), and every POST and stream then needs `Authorization: Bearer <token>`. Streams also accept `?token=`, because browsers can't set headers on `EventSource` or `WebSocket`. Requests whose `Origin` is another site are refused, so a web page you visit can't drive a bus running on your machine. A2A clients send `message/send`, name the skill in `message.metadata.skill` or in a data part `{skill, arguments}`, and get back a message with one data part. A text-only message runs a briefing.
|
|
142
|
+
|
|
143
|
+
**Connectors** (`cortexbus.connectors`) connect the bus to message systems. A source is any iterable of envelopes, and `pump(source, bus)` publishes them. A sink is a callable you attach as a subscription's `handler`, so a failed hand-off goes to the self-healing DLQ like any consumer error.
|
|
144
|
+
|
|
145
|
+
| Connector | Needs | Notes |
|
|
146
|
+
|---|---|---|
|
|
147
|
+
| `JsonlSource(path, follow=True)` / `JsonlSink(path)` | stdlib | tails a file like `tail -f`; bad lines are skipped and reported |
|
|
148
|
+
| `WebhookSink(url)` | stdlib | non-2xx or network error → DLQ `consumer_error`; timeout → `timeout` |
|
|
149
|
+
| HTTP `POST /publish` | stdlib | for producers and webhooks; any JSON value is wrapped as `data` |
|
|
150
|
+
| `KafkaSource(topics, …)` / `KafkaSink(topic, …)` | `confluent-kafka` or `kafka-python` | JSON records; offsets committed after each publish (at-least-once); produce waits for the broker's ack |
|
|
151
|
+
|
|
152
|
+
```python
|
|
153
|
+
from cortexbus.connectors import KafkaSource, KafkaSink, pump
|
|
154
|
+
bus.subscribe(Subscription("fraud-out", intent="account takeover", threshold=0.6, handler=KafkaSink("fraud.alerts")))
|
|
155
|
+
pump(KafkaSource(["payments.events"], bootstrap_servers="localhost:9092"), bus)
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
The Kafka connectors are unit-tested against an in-memory fake of the `confluent-kafka` API. `tests/test_kafka_live.py` also runs them against a real broker when credentials are present (it passed on Aiven's free tier, and CI skips it). `examples/python/kafka_live.py` streams live Wikipedia edits through Kafka into the bus, and `serve` shows the routed feed in a browser. Results are in [conformance/RESULTS.md](conformance/RESULTS.md#live-wikipedia-edits-through-a-managed-kafka-2026-11-19).
|
|
159
|
+
|
|
160
|
+
## Conformance levels
|
|
161
|
+
|
|
162
|
+
| Level | Name | Requires |
|
|
163
|
+
|---|---|---|
|
|
164
|
+
| L0 | Classic | Envelope, exact topics, audit |
|
|
165
|
+
| L1 | Semantic | L0 + embedding tier, semantic subscriptions, dedupe |
|
|
166
|
+
| L2 | Agentic | L1 + LLM tier, schema mediation, summarization, self-healing DLQ, briefings, fan-in |
|
|
167
|
+
|
|
168
|
+
## Status
|
|
169
|
+
|
|
170
|
+
Draft spec v0.1. The reference implementation covers every capability in L0–L2 (table above), plus the optional A2A interface (§9.2). State is in memory, or in SQLite with `--store`. One bus process owns a store: there is no clustering or replication. Connectors cover files, webhooks, HTTP and Kafka. NATS, Redis Streams and SQS fit the same source/sink shape but are not written yet. Feedback is welcome through issues and RFC pull requests against `spec/`.
|
|
171
|
+
|
|
172
|
+
## License
|
|
173
|
+
|
|
174
|
+
Apache-2.0
|
|
File without changes
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
"""Prompt ablation for RESULTS.md: rerun ollama+ollama at δ=0.15 with a minimal judge prompt.
|
|
2
|
+
|
|
3
|
+
Keeps the <message> data boundary but drops JUDGE_SYSTEM's anti-injection and meaning-over-words rules.
|
|
4
|
+
|
|
5
|
+
python -m conformance.ablation_naive_prompt
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
import cortexbus.adapters.ollama as o
|
|
9
|
+
from conformance import run as r
|
|
10
|
+
NAIVE = ("You are the routing judge of a message bus. Decide whether the message between <message> tags "
|
|
11
|
+
"matches the subscriber's intent. Return the verdict JSON: match, confidence, reason.")
|
|
12
|
+
o.JUDGE_SYSTEM = NAIVE
|
|
13
|
+
rep = r.run(r.DEFAULT_FIXTURE, "ollama", "ollama", delta=0.15, calibrate_thresholds=True,
|
|
14
|
+
out=r.REPORTS / "ablation__routing_v1__ollama+ollama__d0.15__naive-prompt.json")
|
|
15
|
+
print(r.summary_markdown(rep))
|