# 2026.02.13 -- v0.5.0-v0.5.2 shipped, roadmap realignment

## Why this matters (product delta)

Before today, qortex was a library you hope works. After today, it's a system you can watch think.

**The core shift**: every operation in the entire stack -- every graph mutation, every embedding call, every bandit decision, every PageRank convergence -- is now instrumented and visible. Open Jaeger and you see an `ingest_manifest` call fan out into 25 child spans covering every node, edge, and Cypher query. Open Grafana and you watch posterior means separate in real-time as the bandit learns which rules work. That's not a developer convenience. That's a demo.

**What this unlocks for the pitch**:

1. *"Show me it learns."* Open the Learning Dynamics dashboard. Feed it 20 observations. Watch the posterior mean for the winning arm climb from 0.5 to 0.95 while the losers sink. That's live, not a slide.

2. *"How do I know it's not just cosine similarity?"* Open Jaeger. Show the PPR trace: 77 iterations, convergence to 9.5e-7, 45 nodes traversed, 32 edges walked. The graph is doing real work, and you can prove it.

3. *"What about cost?"* Every embedding call reports model, batch size, latency. Every bandit selection reports token budget used. The L-MVA (next sprint) will make this self-optimizing: the system discovers the minimum context that maintains quality. But the instrumentation to prove it is already in place.

4. *"Does this work for my app?"* Any downstream consumer (openclaw, langchain-qortex, mastra-qortex) gets the full observability stack for free -- install qortex, call `configure()`, point at the OTel collector. Same dashboards, same traces, zero integration work.

**What changed for competitors**: CrewAI's LTM has `ORDER BY score ASC` (still unfixed -- returns worst results first). Agno's LearningMachine is `json.dumps()` into PgVector with no reward signal. Neither can show you a trace tree. Neither can show you posteriors updating. The observability layer is the moat -- not because it's hard to build, but because it forces you to have something worth observing. They don't.

**The roadmap reorder matters because**:
- L-MVA (#96) is THE pitch line: "the system learns how much context it needs." Token cost is the #1 concern for anyone deploying LLM tools. If we can show budget tiers converging -- live, in Grafana, with the instrumentation we just shipped -- that's fundable.
- Production deployment (#63) is what turns a library into a service. GraphQL for MindMirror federation, REST for pipelines, MCP for agents. One container, three interfaces. That's what makes this a real product, not a dependency.
- Causal DAG (#3) is intellectually exciting but doesn't unlock revenue. Credit propagation is already wired. The structural causal models can wait until the platform is serving traffic.

## What shipped today

**v0.5.0 released** ([GitHub release](https://github.com/Peleke/qortex/releases/tag/v0.5.0), PR #106 merged)

The entire observability layer is now a standalone package (`qortex-observe`) with a unified metrics pipeline:

- 36 metrics in a single declarative schema (`metrics_schema.py`)
- OTel as sole metric backend, PrometheusMetricReader for `/metrics` scrape
- Full trace hierarchy: `@traced` on all 14 MemgraphBackend methods, vec layer (3 embedding models + cache + index ops), and learning (select, observe, credit deltas)
- PPR convergence visible in Jaeger: iterations, final_diff, node/edge/seed counts, latency
- Selective trace sampling: errors and slow spans always exported, normal spans at configurable rate (default 10%)
- Live stack validation script: 132 checks across Prometheus, Jaeger, Grafana
- CI green (4/4), gauntlet clean

92 files changed, ~7K insertions, ~2K deletions. Deleted `prometheus.py` subscriber entirely.

## What got fixed along the way

- CI extra was `observe` but pyproject.toml defines `observability` -- silent no-op that meant OTel SDK was never installed in CI. Fixed.
- ruff format across 36 files
- OTel importorskip guards on test files
- All lint violations resolved (SIM109, SIM102, SIM117, B007, E402)

## Roadmap adjustment

### Old sequence
1. qortex-observe PyPI publish
2. Causal DAG
3. UCB1 -> Track-and-Stop -> L-MVA

### New sequence
1. **#108 -- qortex-observe PyPI publish** + consumer migration + observability stack deployment
2. **#96 -- L-MVA (BudgetLearner)** -- rush straight here, skip UCB1
3. **#63 -- Production deployment** (GraphQL + REST + MCP triple interface) -- biggest platform unlock
4. **#3 -- Causal DAG** -- deferred, credit propagation already wired and flag-gated

### Why skip UCB1

Thompson Sampling already works for both inner bandit (rule selection) and outer bandit (budget tier selection). UCB1 is just another Strategy plugin -- useful for comparison later but not a prerequisite for anything. Track-and-Stop/SOCP is a refinement of *when to stop exploring*, also not a prerequisite.

The thing that matters is L-MVA: the outer bandit that discovers the minimum token budget maintaining quality, per task, per domain. That's the pitch line. The Strategy protocol means we can swap in UCB1 or SOCP anytime without touching the BudgetLearner architecture.

### What L-MVA needs (Issue #96)
- `InferenceTrace` event + subscriber wiring (all 4 subscribers)
- `BudgetLearner` wrapper: outer bandit picks budget tier, inner bandit picks rules under that budget
- `BudgetConfig` dataclass with tier discovery, reward threshold, exploration rate
- MCP tools: `qortex_budget_select`, `qortex_budget_observe`
- Dashboard panels: tier selection rate, budget vs reward correlation, convergence

### What #63 needs
- `LocalQortexClient` wrapping VectorIndex + GraphBackend
- FastAPI app mounting: Strawberry GraphQL (`/graphql`), REST (`/api/v1/`), FastMCP (`/mcp`)
- Dockerfile + compose
- MindMirror federation integration (8th subgraph)

## Releases

- **v0.5.0**: qortex-observe extraction, unified metrics pipeline, full trace hierarchy, selective sampling
- **v0.5.1**: CI fix (observe -> observability extra), ruff format, lint cleanup
- **v0.5.2**: Docs sync -- API reference covers all 33 tools, installation lists 13 dep groups, CLI adds prune + mcp-serve, concepts adds vec/learning/observe

## Issues

- **Created #108**: qortex-observe PyPI publish + consumer migration + stack deployment
- **Closed #66**: observability layer (shipped v0.5.0)
- **Closed #64**: learning layer v1 -- Thompson Sampling, MCP tools, observability complete
- **Closed #100**: docs sync (shipped v0.5.2)
- **buildlog-template PR #164 merged**: roadmap updated with qortex progress

## Next sprint

1. **#108** -- publish qortex-observe to PyPI, migrate consumers, deploy portable observability stack
2. **#96** -- L-MVA: BudgetLearner + InferenceTrace + dashboard panels. The pitch demo.
3. **#63** -- triple interface (GraphQL + REST + MCP). The platform unlock.
