System architecture¶
This is the complete architecture of Venturi for customer architects: where the system runs, how it is partitioned into planes, how attribution is built, where your data lives, and, most importantly, where it does not. It is the reference to hand to whoever reviews Venturi before it goes into your environment.
If you only need to connect and start seeing attribution, start with the Quickstart. If you want the security-reviewer summary, read Trust & security. This page is the architecture underneath both.
The one-sentence model
Venturi is the attribution layer for AI: designed to become the enterprise system of record for AI consumption. It deploys as a dedicated data plane inside a dedicated single-tenant boundary, reads cost/usage/identity signals, correlates AI invocations to the team, service, identity, and budget responsible, and, by design, does not block your AI traffic (fail-open) and has no schema field for prompt or completion content.
Deployment model: dedicated data plane¶
Venturi runs as a dedicated, single-tenant data plane. Self-hosted mode places it in your VPC, project, or subscription. SaaS mode places the same logical plane in a Venturi-operated environment pinned to your contracted residency lane. Your operational data stays in that tenant boundary. The separate control plane delivers signed releases and configuration and never holds raw tenant data.
Three product invariants follow directly from this shape:
- Your operational data stays in the dedicated tenant boundary. Venturi’s shared development, certification, and release-rehearsal environments do not hold customer operational data.
- Integrations are read-only. Venturi reads cost, usage, and identity. It never writes back into your environment. This is enforced, not promised: see Trust & security.
- The decision-time interceptor fails open. It never depends on an external control plane to let your traffic through.
Outbound-only data-plane fetches
The tenant data plane reaches out for signed release artifacts and configuration. There is no inbound path from Venturi’s control plane into your data. Server-initiated outbound calls to customer-named endpoints (billing hosts, connectors, webhooks) pass through a single hardened fetch wrapper with private/link-local/metadata-IP denial and DNS-rebind protection, so a connector can never be coerced to reach your instance-metadata service or internal hosts.
The three planes¶
Venturi partitions cleanly into three planes with different latency profiles, different failure semantics, and different responsibilities. Keeping them separate is what lets the synchronous path stay fast and fail open while the analytics path stays correct and durable.
| Plane | Job | Path | Failure mode |
|---|---|---|---|
| Decision-time interceptor | Observe live AI invocations at decision time | Synchronous hot path | Fails open: forwards your traffic, by design, even under platform failure |
| Attribution processor | Build the attribution graph and confidence | Asynchronous, off the hot path | Reconciles later; never on the request path |
| Dashboard / API | Serve attribution to people and systems | Synchronous read | Fails closed: denies on auth/tenant error |
Decision-time interceptor plane (synchronous, fail-open)¶
The interceptor plane optionally sits in the decision-time path of an AI request. Its only job there is to observe: record that an invocation happened and what identity/service made it, and forward the request unmodified. It performs a fast index lookup, not inline model inference, and emits an event onto the stream for the processor plane to attribute asynchronously.
This plane runs on a hard 50 ms P99 end-to-end latency budget, enforced with a wall-clock timeout. Internal calls behind the interceptor (index lookup, policy evaluation) fit inside a 15 ms internal budget. Its only runtime dependencies are the fast in-memory index and the event stream: no graph database call ever enters the hot path.
Fail-open is absolute on this plane
No code path on the AI hot path may block your AI traffic. If anything is slow, degraded, or down, the request is forwarded unmodified and attribution is reconciled later from the event. This is enforced by a wall-clock timeout outside application logic. See Fail-open vs fail-closed.
The decision-time interceptor is not the only way Venturi sees traffic. Venturi
classifies AI pathways with the governed PathwayCategory taxonomy, covering
direct APIs, gateways, routers, cloud model platforms, orchestration frameworks,
agentic AI, embedded SaaS, developer tools, self-hosted models, batch APIs, and
automation workflows. It captures each through whichever of six capture
layers is feasible:
| Layer | Source | Example |
|---|---|---|
| L1 | Network proxy / gateway | Live interceptor, AI gateway |
| L2 | SDK / framework | Orchestration-framework instrumentation |
| L3 | Billing / control-plane | CUR, BigQuery billing export, Cost Management |
| L4 | Observability pipelines | OpenTelemetry, metrics |
| L5 | Source-of-record systems | HRIS, IdP, repository ownership |
| L6 | Vendor admin APIs | Provider usage/cost and audit-log APIs |
Each event carries a capture-feasibility class so the system is honest about what is fully capturable versus indirectly capturable versus uncapturable for a given pathway; it never silently treats missing visibility as zero.
Attribution processor plane (asynchronous)¶
The processor plane consumes the event stream and does the real work of attribution: running the RAIL pipeline, building the attribution graph, computing calibrated confidence, and materializing results into the index that the dashboard reads. This is where 95%+ of attribution volume is handled, off the synchronous path, on a generous 100 ms inference design budget measured at the processor seam. Because it is asynchronous and event-sourced, it can take the time to be correct without ever touching your live traffic.
Dashboard / API plane (synchronous reads, fail-closed)¶
The dashboard and developer API serve attribution to your engineers, finance team, and systems. Reads are served from the materialized index at low latency. Every result carries its interpretation metadata (see Evidence on every result), so a number is never shown with more authority than its evidence supports. This plane is the fail-closed half of the system: authentication, authorization, tenant isolation, exports, and billing all deny on error.
The six-layer attribution graph¶
Venturi’s defensibility is the attribution graph: it correlates the AI inference signals it can see across six layers into one graph, designed to work without relying on manual tagging.
The product “six-layer” framing maps to an engineering canon of five node types plus a budget edge:
| Product layer | Graph node | Answers |
|---|---|---|
| Invocation | Invocation |
Which AI call happened? |
| Service | Service |
Which service or workload made it? |
| Code / Project | Project |
Which codebase / project owns that service? |
| Identity | Identity |
Which person or service account is responsible? |
| Organization | Organization |
Which team / org unit do they roll up to? |
| Budget | (edge on Organization) |
Which cost center / budget is billed? |
Budget responsibility is an attribute of the organization expressed through
billed_to / budgeted_under edges, not a separate node. The graph uses a
frozen eight-edge wire taxonomy (owns, member_of, deployed_in, called_by,
produced_by, billed_to, owned_by_org, budgeted_under) so that every
relationship a result depends on is explicit and auditable.
The result answers the question finance and engineering both ask: which team, which service, which person, which budget is responsible for a given slice of AI spend, and it is designed to do so without relying on manual tagging.
The RAIL three-stage pipeline¶
RAIL (Reconciliation Attribution Intelligence Layer) is Venturi’s platform runtime and customer-facing attribution term. It turns raw invocation signals into attributed, confidence-scored records in three stages. RAIL is not Stage B only: it spans deterministic resolution, inference and training, fractional allocation, evidence, uncertainty, mapping, anomaly interfaces, and feedback-loop learning. Its research and training machinery supplies verified Stage B models; that machinery is part of RAIL, not a separate customer-facing system.
Stage A: deterministic resolution (R1–R5)¶
Stage A resolves what can be known for certain, using five deterministic reconciliation methods:
| Method | Reconciliation signal |
|---|---|
| R1 | Direct key match (API key / service-account identifier) |
| R2 | Temporal proximity |
| R3 | Naming correlation |
| R4 | Historical patterns |
| R5 | Service-account trace |
Stage A is deterministic and machine-learning-free: the same input always
yields the same AttributionRecord fields, and no model runs in this stage.
Anything Stage A resolves carries stage_origin = stage_a and the strongest
confidence the evidence allows. This is the backbone of chargeback-grade
attribution.
Stage B: trained edge-existence inference¶
For edges Stage A cannot resolve deterministically, Stage B asks a narrower question (does this edge exist?) and answers it with a trained attribution model that runs inside the attribution processor, as described in the next section. The model emits a posterior per edge, which is calibrated and materialized into customer-facing confidence.
Stage B is wrapped in fallback behavior at every level. The inference call carries a hard 20 ms wall-clock budget, which is the adapter’s share of the synchronous 50 ms interceptor budget; the asynchronous processor’s 100 ms P99 inference budget is a separate figure and never sits on the synchronous path. If the call exceeds its budget, is missing its artifact, returns an invalid output, sheds under concurrency, trips its circuit breaker, or is disabled for that edge, the pipeline falls back to a deterministic heuristic baseline: a permanent safety feature that keeps attribution flowing. Stage B is not on the production-traffic path and never makes a result fail; it only improves the attribution that the deterministic path already guarantees.
Stage C: fractional cost allocation¶
When an invocation genuinely cannot be pinned to a single owner, Stage C allocates its cost fractionally across the candidate owners using the R6 allocation prior. R6 carries explicit allocation semantics and a deliberate 0.50 ceiling on the prior itself. R6 is refused outright as evidence for whether an edge exists, not merely clamped, and the system is transparent that an allocation is an allocation, not a resolution. Allocated attribution lines carry their own operational-confidence ceiling: 0.70 where proportional allocation signals are present, and 0.50 where the split rests on no such signal. Both sit below the 0.80 chargeback floor, so an allocated line can be at most provisional, never chargeback-ready. (The numbers describe different things: 0.50 bounds the allocation prior itself; 0.70 and 0.50 bound the confidence of an allocated line.)
The output of the pipeline is the AttributionRecord: the durable, auditable
unit that carries the resolved edge, its output_state, its calibrated
confidence (coper), the originating stage, and the evidence behind it.
Six output states¶
Every result lands in exactly one of six honest output states; Venturi never fabricates a default when it does not know:
output_state |
Meaning |
|---|---|
deterministically_resolved |
Resolved with certainty by Stage A |
strongly_inferred |
High-confidence Stage B inference |
bounded |
Narrowed to a set; not a single owner |
ambiguous |
Multiple plausible owners remain |
unknown |
Insufficient evidence to attribute |
not_identifiable |
Cannot be attributed even in principle |
How Stage B is served¶
Stage B runs in-process inside the attribution processor, in your data plane. There is no separate inference service, no additional listener, and no network hop: the processor loads the model artifact into its own runtime, performs feature extraction and edge-existence inference, emits confidence and evidence semantics, and falls back to the deterministic heuristic baseline on timeout, missing artifact, invalid output, concurrency shed, circuit-breaker trip, or a disabled flag.
Model artifacts are delivered out of band rather than fetched on the request path. They are staged into the processor’s own storage before it starts, mounted read-only, and hash-verified before they are bound; verification failure refuses the artifact and the baseline answers instead. The models themselves are produced by Venturi’s internal research program and promoted through the human-gated process described below.
The seam is deliberately narrow. It is not a customer-facing app, a training UI, or an authorization boundary. It supplies evidence-backed predictions through one contract and owns nothing else: it does not own dashboards, billing, admin mutation, security controls, or exports.
What confidence means and how to act on it¶
Every attribution carries a single customer-facing confidence value, coper,
on a 0–1 scale. Two numbers govern how you use it:
| Threshold | Value | What it means |
|---|---|---|
| Confidence cap | 0.95 | The highest confidence Venturi ever asserts. This is a deliberate, conservative policy ceiling; Venturi never claims certainty on an inferred attribution. |
| Chargeback floor | 0.80 | An attribution must be at or above this to be eligible for chargeback and to count toward a savings-share billing base. |
So in practice: anything at 0.80 or above is solid enough to bill and charge back; below it, treat the attribution as advisory and investigate before acting. Venturi caps inferred confidence at 0.95 by policy: when you see a number that high, it means “as confident as we will ever assert,” not “certain.”
How the model is improved, and who decides
The production attribution model is selected and promoted by a human Venturi decision through a formal gate, never automatically. Promotion requires per-edge precision and calibration bars to clear, a non-waivable cap on high-confidence errors, and a canary rollout that auto-rolls-back without ever touching customer traffic if calibration drifts. The most explainable model wins ties. You consume the result of that discipline; you never have to operate it.
Evidence on every result¶
No attribution is presented as a bare number. Every customer-visible result carries interpretation metadata, shown in the evidence drawer, so you can always see why and how strongly Venturi believes it:
stage_origin: Stage A deterministic, Stage B inference (trained model or heuristic baseline), or Stage C allocation.output_state: one of the six states above.coper+ confidence band: the calibrated confidence and where it sits.- Evidence basis: which reconciliation methods (R1–R5) and which input evidence produced the result.
- Model version: the attribution-model artifact version, where applicable.
- Result source: trained model or deterministic heuristic baseline.
- Degradation state: whether the system was running fully or in a fallback/degraded mode when the result was produced.
- Demotion reason: calibration drift or model age when a previously eligible edge is capped below the chargeback floor.
- Freshness: when the underlying data was last reconciled.
This metadata travels with the result everywhere it is shown: the same record backs the dashboard row, the evidence drawer, the dispute, and the export line. The absence of any required value is rendered explicitly as “unknown / unavailable,” never as a blank or a fabricated default. This is the honest-unknown discipline: Venturi would rather tell you it does not know than guess.
Control plane vs data plane¶
| Dedicated tenant data plane | Control plane (no inbound initiation) | |
|---|---|---|
| Holds | Your events, graph, index, attribution records | Releases, configuration, licensing |
| Holds your data? | Yes, and only here | No |
| Direction | Internal to the self-hosted or SaaS tenant boundary | Data plane initiates outbound fetches only |
| Customer data egress | None | None |
Your data plane is the only place your operational data lives. The data plane fetches signed, verified release artifacts and configuration from the control plane; the control plane never reaches into your data. There is no path by which Venturi’s control plane reads your invocation events, your graph, or your index.
Fail-open vs fail-closed: the boundary¶
The single most important rule in the architecture is the fail-open boundary, and it is drawn precisely:
Fail-open applies to exactly one path
Fail-open applies only to customer AI traffic on the AI hot path. If Venturi is degraded, your AI request is forwarded unmodified and attribution is reconciled later. Venturi cannot take your AI traffic down.
Everything security-relevant fails closed
Fail-closed applies to every security-relevant decision: authentication, authorization (RBAC), tenant isolation, admin mutation, export creation, billing mutation, data-residency routing, legal-gated adoption/workforce views, and support break-glass access. On error, timeout, ambiguity, or missing input, these deny, with zero data egress and an audit entry.
This split is exhaustive and frozen. There is no feature flag that converts a fail-closed path to fail-open. The decision-time interceptor forwards your traffic when in doubt; the security boundary denies access when in doubt. Both behaviors are tested directly.
Where customer data lives: and where it does not¶
| Data | Where it lives | Where it never goes |
|---|---|---|
| Invocation events, attribution graph, materialized index | In the dedicated tenant data plane (your cloud in self-hosted mode or your contracted SaaS lane) | Venturi’s control plane or shared environments |
| Cost / usage / identity signals | Read into your data plane | Written back to your environment (read-only) |
| Prompt and completion content | Nowhere persisted | Optional provider connectors discard bodies and content-shaped keys in memory; the normalized schema has no content field |
| Provider admin keys | KMS-encrypted in your tenant boundary | Venturi control plane never sees plaintext |
No content capture, by design
The core pipeline never stores prompt or completion text. The canonical
InvocationEvent schema has no content field at all. Attribution is
built entirely from metadata: model, tokens, cost, identity, timing. This
is structural, not configurable: there is no setting that turns content
capture on.
Data that does live in your plane is retained for 13 months operationally, encrypted at rest with a customer-managed key (one key per tenant) and in transit with TLS. Per-subject erasure is supported via crypto-shred within a 30-day SLA. See Trust & security for the full data-handling model.
Energy and carbon attribution¶
Because the attribution graph already knows which model served each invocation and how many tokens it consumed, Venturi projects the same graph onto energy and carbon accountability. Each invocation is attributed energy (Wh/kWh) and carbon (gCO2e) from a model-and-region catalog, rolled up the same six layers so a team, service, or budget can see its AI energy and carbon alongside its cost.
Null is not zero
When a model is not in the energy/carbon catalog, Venturi reports the value as null (unknown coverage), never as zero. It will not understate impact by treating missing catalog coverage as no impact, and energy multipliers are never restated as cost figures.
How it fits together¶
- To connect a cloud and start producing attribution, see Quickstart and the onboarding guides.
- To send request-level events for per-call resolution, see Ingestion.
- For the security-reviewer view of read-only enforcement, no-content-capture, and fail-open, see Trust & security.
- For a shorter conceptual overview, see How Venturi works.