Documentation · Concepts & architecture
This is documentation for people evaluating how Spotonix works — the agentic analyst that interprets a business question before it queries. It explains the core objects, the execution model, and the current boundaries in plain language.
Spotonix is pre-GA. What follows is an honest conceptual and architectural overview, not an API reference — deeper operational documentation (setup guides, an API and SDK reference, connector specifics) is being written and ships with general availability. Coming soon Operational reference
Prerequisites
Three things need to be configured before Spotonix can interpret and answer questions. Exact hosting, credentials, network paths, connectors, and retained artifacts are confirmed per engagement; the list below is the conceptual shape, not a deployment guarantee.
Core concepts
Six terms carry the model. Everything else in the documentation is built out of these. They are the vocabulary Spotonix uses internally and externally, so learning them once makes the rest of the system legible.
The domain-context layer used during interpretation. It represents Segments, Calculations, Analysis Patterns, schema relationships, and other configured business context. Storage, persistence, and export behavior are documented for the deployment.
The who. Segments name the cohorts, store sets, product groups, and other populations your analysis is about. A Segment makes the selected population explicit in the plan; cross-question retrieval and versioning are evaluated separately.
The how much. Calculations are the measured quantities — growth, ratio, rate, benchmark, time comparison. A Calculation makes the selected computation explicit and reviewable.
The reusable analytical intent — the semantic glue that binds Segments and Calculations into a repeatable analytical shape. A pattern is the "how we look at this" that recurs across questions. It separates analytical structure from the wording of one prompt.
The mechanism. Intent Algebra reads a business question and resolves its definitions, calculations, scope, filters, and ambiguity into a visible plan composed from the primitives above. In Copilot mode, the plan is accepted before query generation continues; generated SQL is then checked against material plan bindings before execution.
The analytical result produced after query execution. Persistence, scheduling, alerting, reuse, and access behavior depend on the active workflow and deployment configuration.
How it behaves
Three behaviors define how a question becomes an answer. They are described here conceptually; the operational detail behind each arrives with the GA reference.
Spotonix shows the plan—Segments, Calculations, scope, filters, and grain—before SQL executes. Material unresolved business meaning can trigger clarification; some permitted assumptions remain part of the interpretation policy.
In Copilot mode, the executor pauses after interpretation and waits for plan confirmation before query generation continues. Assistant mode does not use the same pause, so the gate is not described as universal across personas.
The query generator receives the original question and the plan. Semantic checks validate material bindings in the generated SQL before execution. This is not a deterministic plan-to-query compiler and does not guarantee identical SQL across repeated runs.
The visible interpretation and validation behavior is the differentiator. For the mechanism in depth, see Intent Algebra; for the deployment and identity model, see Architecture.
Limitations & status
An honest evaluation needs the boundaries stated plainly. These are the current edges of both the product and its documentation. Where something is in progress, it carries a status label rather than a promise.
Deployment topology, supported surfaces, and control specifics are worked through against your real environment with design partners — not asserted from a reference diagram.
Related references