# Agentic Data Intelligence - Docs > Documentation for Agentic Data Intelligence (ADI) - AI agents for data engineering and analytics. --- # What is Agentic Data Intelligence? Agentic Data Intelligence (ADI) is the control plane for AI data analytics. It sits as a thin layer between agents and your data, generating a machine-readable model of what your data means and an enforceable contract that constrains how AI agents use it. The result is consistent, trustworthy analytics above the stack you already run. ADI augments a stretched team rather than replacing it, and extends your existing catalogue and governance rather than replacing them. ## Business meaning is the missing layer Business meaning is scattered across SQL, dashboards, documentation, and people's heads. No layer in the modern data stack owns it, so every tool downstream, agents included, works with incomplete context. Two dashboards, same question, different numbers. That is not a tooling problem. It is a meaning and trust problem. ## Why copilots have not closed the gap The modern data stack has never been more capable: cloud warehouses, transformation frameworks, metrics stores, BI tools, and now AI copilots. Yet most organisations still struggle to turn raw data into answers they can trust. Copilots write SQL quickly from a natural-language question. They just cannot tell you whether the answer is right. They pattern-match against a schema without knowing what the metrics actually mean or which calculations are valid. Because the LLMs behind agents are non-deterministic, the same question can produce different SQL and different numbers, with no way to tell which is correct. ## How ADI is different ADI works out what your data means first, then holds agents to it. It builds an explicit, machine-readable model of your business semantics and an enforceable contract: the metric definitions, the valid dimensions, the allowed joins, the governance rules, all defined once. Every agent, every session, and every query works from the same definitions, and generated SQL is held to them. Correctness is the starting point. If a question cannot be answered correctly within the contract, ADI says so rather than guessing. Keep the copilots and agents you already use. ADI works above them, constraining how they query the data and holding them to what the metrics mean. ## Human-in-the-loop ADI does not act alone. You approve changes to the semantics and the contract. The process is transparent: changes are explicit, versioned, and reviewable. The human role shifts from writing routine SQL to defining what matters to the business and deciding what to do with the answers. ## Two editions, one control plane Whether through a Skill in a coding agent or a native app in your warehouse, ADI brings the same semantic understanding and enforcement to data work. **Starter Edition** is for individual developers, data engineers, and analysts adding semantic and control functionality to the agents and agentic workflows they use for data analytics. It is delivered as a plugin that bundles the ADI Skills and MCP server, which can also be installed individually, for coding agents and IDEs. **Enterprise Edition** brings the same semantic and control layer to teams using copilots and agents on cloud data and analytics platforms, where governance, accuracy, and consistency matter most. It runs as a native app inside your own warehouse and extends, rather than replaces, your existing catalogue and governance. Both editions carry the same positioning, the same control-plane principle, and the same human-in-the-loop model. ## Company background Agentic Data Intelligence SA is a Swiss company, headquartered in Geneva and backed by leading venture capital firms, founded in 2021. ADI was built from first-hand experience with on-chain blockchain data, some of the most complex data there is to interpret, where the scalability and trust challenges are the same ones data teams meet every day. Starter Edition is entering Closed Beta and Enterprise Edition is in limited Alpha. Request early access at [agentic-data.com/access](https://agentic-data.com/access). - **Website:** [agentic-data.com](https://agentic-data.com) - **Resources:** [agentic-data.com/resources](https://agentic-data.com/resources) - **X / Twitter:** [@agentic_data](https://x.com/agentic_data) --- # How ADI Works ADI builds explicit understanding of your data before anything acts on it. That understanding is structured into four layers, each adding a level of meaning on top of the one below, and expressed as a machine-readable semantics summary and an enforceable contract. ## The four-layer architecture ### 1. Data Asset Layer (DAL) What data physically exists and how it is structured: schemas, tables, columns, keys, and relationships. This is the raw catalogue of everything in your data. ### 2. Business Model Layer (BML) What the business cares about. Entities (like organisations, users, projects), events (like signups, purchases), and the relationships between them. This layer maps the physical data to business concepts. ### 3. Analytical Model Layer (AML) How the business can be measured. Dimensions (like country, time period), metrics (like project count, total budget), and the rules for how they are calculated and aggregated. This is where measurement becomes standardised. ### 4. Consumption Contract Layer (CCL) How users and agents are allowed to ask questions. Supported intents, default behaviours, and guardrails. This is the system-level enforcement of correctness: a request the contract cannot answer correctly is refused, not guessed at. ## The agentic loop ADI operates in a continuous cycle: 1. **Sense**: detects changes in data and schema. 2. **Understand**: continuously updates its semantic model. 3. **Answer**: responds to questions within explicit semantic boundaries. 4. **Enforce**: holds agents and copilots to the contract, so queries use the data the way the semantics allow. 5. **Learn**: incorporates reviewed feedback and system behaviour. This cycle means ADI adapts as your data and business evolve, rather than requiring manual updates every time something changes. Updates to the semantics and the contract are explicit, versioned, and reviewed, so they can be approved, tested, and rolled back. ## What ADI changes Building trustworthy analytics has always depended on business meaning that no layer in the stack actually owns, so every downstream tool, agents included, works with incomplete context. Traditionally, closing that gap meant chaining together separate stages, each owned by a different role. Someone profiles the warehouse. Someone designs the semantic layer: the metrics, the dimensions, the rules. Someone wires governance around it. Two or three people, days to weeks for a first pass, and ongoing effort every time a schema or business rule changes. The business semantics stay implied in models and documentation, maintained by hand, and every handoff is a place where meaning gets lost. Copilots and agents made querying faster but riskier too: they generate answers quickly, nothing checks whether the answer is valid, and the same question can return different numbers. ADI gives business meaning an explicit, machine-readable home and an enforceable contract above the stack you already run. Agents keep doing the querying. ADI holds them to what the metrics actually mean. Your team still governs and refines the model, but the heavy lift no longer depends on filling multiple specialist seats for weeks at a time. ## Five layers of value ADI adds five capabilities that raw data access leaves to chance: 1. **Semantic abstraction.** Metrics are queried by name, not by schema knowledge. A team defines "total budget" once, and every agent works from the same definition. 2. **Governance in the contract, not the prompt.** PII and disallowed group-bys are refused before any data is touched, and generated SQL is restricted to read verbs. Because the rules live in the contract, an out-of-contract request is refused when the SQL is generated, whatever the agent is prompted to do. 3. **Multi-agent consistency.** Every agent working from the same contract receives the same SQL for the same request, so within a shared contract the same question yields the same answer. 4. **Provenance.** Every query returns a traceable chain: which metric was measured, which governance checks ran, how tables were joined, and what time window was applied. 5. **Signature-gated execution, at the execution tiers.** Where a tier runs execution (self-hosted or fully hosted), generated SQL carries a signature attesting it was compiled from the contract, and only signed SQL runs through the verified path. The current Beta runs at t1, which generates and validates SQL for you to run in your own environment. ## Minimal footprint ADI works from schema and context, not the data itself, so your underlying data stays where it is and analysis runs in your own environment. ADI holds only the meaning and the rules. --- # Use Cases ADI serves different users depending on the edition. Starter Edition is for individuals working with coding agents and IDEs. Enterprise Edition is for teams adding a semantic and control layer to copilots and agents on cloud data platforms. ## Starter Edition use cases ### Developers adding semantic and control functionality to agentic workflows Individual developers building AI agents can give those agents governed, meaning-aware data access without writing custom data logic. The ADI plugin, bundling the Skill and MCP server, provides the semantic layer, the governance rules, and contract-checked SQL. The developer's agent works in business terms and receives verified, provenance-tracked results. ### Data engineers extending coding agents Data engineers working in Claude Code, Cursor, or other coding agents can query governed data within their existing workflow. The contract keeps metric definitions consistent across sessions and agents. Schema knowledge is not required: the contract defines the valid surface area. ### Analysts using AI agents for governed queries Analysts who work with AI agents can ask questions governed by the contract. ADI refuses questions that fall outside the contract and points to safe alternatives. The analyst gets answers backed by a declared definition, with provenance showing how those answers were derived. ## Enterprise Edition use cases ### Teams governing the copilots and agents they already run Teams adopting copilots and agents on the warehouse often hesitate, because they cannot trust what the agent does with the data. ADI adds the semantic and control layer above those tools: it constrains how they query and enforces what the metrics mean, so business users can self-serve through an agent without the team losing control. ### Consistent, governed self-serve analytics Ask questions in business language and get validated answers with provenance. Because the contract defines the metrics once, every user, session, and agent works from the same definitions, so the same question returns the same answer within that shared contract. Governance is applied by the contract rather than left to policy on paper. ### Managing change and drift Semantics go out of date fast. When source schemas or business rules change, ADI detects the change, updates its understanding, and keeps enforcement consistent across all downstream consumers. Changes to the semantics and contract are versioned and reviewed, so they can be rolled back. ### Cross-domain data work ADI works across data domains: financial data, operational data, marketplace data, even blockchain data, whether your own or from marketplaces. The same four-layer architecture applies regardless of the business domain. The contract defines what the data means and how it can be queried, and that approach is domain-agnostic. ## Platform integrations ### Starter Edition **Dedicated plugins:** Claude Code, Cursor, Codex. **Compatible plugins and skills:** OpenClaw, Manus, and any other coding agents that support either the Open Plugins Specification or the Agent Skills Specification. **Delivery:** the ADI plugin, which bundles the Skills (Agent Skills Specification / SKILL.md) and an MCP server (Model Context Protocol, built on FastMCP); the Skills and MCP server can also be installed individually. Domain Packages for different data types are planned for future releases. ### Enterprise Edition **Data platforms (available now):** Snowflake, Databricks. **Data platforms (coming soon):** Google BigQuery, Amazon Redshift. **Interoperability:** The contract's analytical model can be output to MetricFlow, with two-way Open Semantic Interchange (OSI) compatibility planned for a future version. --- # Starter Edition Overview Starter Edition is ADI for individual developers, data engineers, and analysts. It adds semantic and control functionality to the agents and agentic workflows they use for data analytics, delivered as a plugin that bundles the ADI Skills and MCP server, for coding agents and IDEs. ## Who it is for Starter Edition is built for people who work with coding agents and want their agent's data work to be governed and consistent. That includes: - Developers building AI agents that need reliable, meaning-aware data access - Data engineers extending their IDE-based agents with semantic understanding and enforcement - Analysts using AI agents to query data with correctness built in ## How it is delivered The primary way to install Starter Edition is the **ADI plugin**, which bundles both parts below into a single install. Dedicated plugins are available for Claude Code, Cursor, and Codex; see Getting Started for the install commands. OpenClaw, Manus, and any other coding agents that support either the Open Plugins Specification or the Agent Skills Specification can also use ADI, and this is also the route if you simply prefer installing the parts separately: install the two components individually. **Skills** following the Agent Skills Specification. A Skill teaches an agent how to work with ADI: which tools to call, in what order, how to author and validate a contract, how to handle refusals, and how to present results. The same logical content works across supported platforms with minimal variation. **MCP server** exposing ADI's tools over the Model Context Protocol, so the agent can discover capabilities, author and validate a contract, and generate contract-governed SQL. Domain Packages for different data types are planned for future releases. ## Trust tiers Starter Edition runs across three different trust tiers that reflect how much of the workflow the platform runs on your behalf. With **t1**, ADI runs a hosted MCP server that your agent connects to. It generates and validates contract-governed SQL with full provenance, but does not execute it or read your warehouse: the contract is built from schema and context alone, and you run the generated SQL yourself. Your data never leaves your environment; ADI holds only the meaning and the rules. Two further tiers are planned for future releases: **t0** (self-hosted) and **t2** (fully hosted with credentials). These are the execution tiers, where the server runs the generated SQL directly and gates execution by signature. ## What is included - Discovery of the active trust tier, enabled tools, and features - Contract authoring and machine validation against ADI's canonical schema - Contract-governed SQL generation from business-language questions - Governance defined in the contract and applied when SQL is generated (PII and disallowed group-bys, join safety, cardinality guardrails, read-only SQL) - Provenance on every generated query, showing how the answer was derived - Refusal handling with recovery information and safe alternatives ## How it compares to Enterprise Edition Starter Edition focuses on individual developer workflows through coding agents which could be on local data, or connected to data warehouses via other connectors. Enterprise Edition brings the same semantic and control layer to teams using copilots and agents on cloud data and analytics platforms, with fuller semantics, stricter governance, and a native app that runs inside the customer's own warehouse. Both editions share the same control-plane principle: understand the data first, then hold every query to the contract. ## Current status Starter Edition has graduated from Alpha testing and is entering a Closed Beta, ahead of a later Open Beta. The Closed Beta puts the control plane in the hands of external testers. It checks three things: that the workflow holds on real data (connect, author and validate a contract, generate governed SQL, act on the results); that governance holds (disallowed group-bys, unsafe joins, and out-of-contract requests are refused with useful recovery information); and that the experience is smooth from setup to a first governed answer. An earlier internal alpha validated the core workflow, so this round focuses on real-world use rather than first-run setup. Testers get direct access to the ADI team and help to shape what gets built next. Request early access at [agentic-data.com/access](https://agentic-data.com/access), follow Getting Started for setup, and see the Beta Notes and Known Issues page for current limitations and practical guidance. --- # Getting Started with Starter Edition This guide walks through installing ADI Starter Edition in your coding agent, connecting and authenticating, and running your first governed query in the Beta. > [!NOTE] > **What the Beta covers.** The Beta runs at trust tier t1, which is generation-only. Your agent can discover capabilities, author and validate a contract, and generate contract-governed SQL with full provenance. At t1 the server does not execute SQL or read your warehouse, so you run the generated SQL in your own environment. Execution and warehouse access arrive with the t0 and t2 tiers (see the Starter Edition overview). ## Prerequisites - A supported coding agent: Claude Code, Cursor, or Codex via a dedicated plugin, or OpenClaw, Manus, and any other coding agents that support either the Open Plugins Specification or the Agent Skills Specification, via individual install - A Zitadel account for authentication. You are prompted to sign in or create one when you connect; your account needs the analyst (query) role and an approved status before you can run queries - The MCP endpoint, provided to you directly when you are accepted into the Closed Beta - Optionally, a dataset of your own, plus a short description or data dictionary of it (see Step 4 for why). ADI also provides a synthetic dataset with a ready-made contract. ## Step 1: Install ADI The quickest way to install Starter Edition is the **ADI plugin**, which bundles the ADI Skills and the MCP server configuration in a single install. **Dedicated plugins** are available for Claude Code, Cursor, and Codex: - **Claude Code:** `/plugin marketplace add agentic-data-intelligence/adi-starter`, then `/plugin install adi` - **Codex:** `codex plugin marketplace add agentic-data-intelligence/adi-starter`, then `codex plugin add adi@adi` - **Cursor:** `git clone https://github.com/agentic-data-intelligence/adi-starter.git`, symlink its `plugin/` folder to `~/.cursor/plugins/local/adi`, then reload Cursor Once installed, you have the two ADI Skills (authoring and querying) and the ADI MCP server available in your agent, giving it the full workflow: discover capabilities, author and validate a contract, generate contract-governed SQL, and handle refusals. **Compatible plugins and skills.** OpenClaw, Manus, and any other coding agents that support either the Open Plugins Specification or the Agent Skills Specification can use ADI this way, and it is also the route if you simply prefer installing the parts separately. Copy the two Skill folders (`adi-querying` and `adi-authoring`) into your agent's skills directory, then configure the ADI MCP server in your client by pointing it at the endpoint provided to you on acceptance. The MCP configuration is a small JSON block naming the server and its URL, for example: ```json { "mcpServers": { "adi": { "type": "http", "url": "" } } } ``` Where this file goes depends on your client (for a Claude Code or Cursor-style layout, `.mcp.json` in your project root); check your client's own MCP documentation for the exact location. **Not yet invited?** Closed Beta access is invite-only. Installing the plugin or the Skills without an approved Zitadel role gets you as far as sign-in, but queries return a pending status until access is granted (see Step 2). If you would like to be invited, request early access at [agentic-data.com/access](https://agentic-data.com/access). ## Step 2: Connect and authenticate However you installed, connecting to the ADI MCP server requires authentication. The server is reached over streamable HTTP; on first connection you sign in with, or create, a Zitadel account. There is no API key. Zitadel is a Swiss-headquartered identity and authentication platform, and ADI uses it with data residency in Switzerland. You can find more information at [zitadel.com](https://zitadel.com) and in its [privacy policy](https://zitadel.com/docs/legal/policies/privacy-policy). During account creation you also accept Agentic Data Intelligence SA's [Terms of Service](https://agentic-data.com/terms) and [Privacy Policy](https://agentic-data.com/privacy), which govern Starter Edition use. If your access is still being approved, the tools report a pending status until it is active. ## Step 3: Discover capabilities Once connected, have your agent call `adi.get_capabilities`. This returns the active trust tier, the enabled feature set (including whether SQL execution is available), and the list of tools you can use. Expect trust tier `t1`, the four ADI tools (`adi.get_capabilities`, `adi.get_authoring_spec`, `adi.generate_query`, `adi.validate`), and your account showing the analyst role with an approved status. It is the equivalent of checking what the server will let you do before you start. ## Step 4: Choose your data and contract ADI works with any dataset. A query is only ever generated against a contract, so you need one of the following. **Use the provided synthetic dataset.** ADI ships a synthetic dataset as a DuckDB file that you can use to try the workflow end to end without connecting your own data. It comes with a ready-made contract, so you can go straight to asking questions. Even if you plan to author for your own data, it is worth asking your agent to show you this contract bundle first: its entities, metrics, and vocabulary documents are a concrete, working example to pattern your own contract against, rather than starting from the abstract structure alone. **Author your own contract.** For your own data, have your agent call `adi.get_authoring_spec` to fetch ADI's canonical schema and authoring guidance, then author the contract bundle (the entities, metrics, dimensions, policies, and rules that describe your data). The authoring step draws on the domain context you provide, the definitions and which columns are sensitive, not just column names, so have a short description or data dictionary of your data to hand. At t1 the server does not read your warehouse, so you author from the spec and your own knowledge of the data rather than from server-side table introspection. Validate it with `adi.validate` before use. Validation catches real structural and semantic errors that a manual review misses, and returns path-pointed messages telling you what to fix. At t1 it checks the contract's structure and meaning, not the contract against your real tables, so a clean result confirms the contract is well-formed, not that it matches your warehouse exactly. ## Step 5: Ask a question Ask in business language, not SQL. For example: - "How many projects are there in total?" - "What is the total budget by country?" - "Show me the top 5 organisations by project count" Guided by the Skill, your agent turns your question into a structured request and calls `adi.generate_query` against the contract. It receives contract-governed SQL plus provenance: which metric was used, how tables were joined, and what filters and time window were applied. Generation is deterministic. The same structured request returns byte-identical SQL every time, so within a given contract the same question yields the same answer. ## Step 6: Run the query You run the generated SQL yourself, in your own environment (your warehouse or a local engine); ADI does not execute it or see your data. Signature-gated execution, where only contract-compiled SQL runs through a verified path, is a capability of the execution tiers (t0 and t2). ## Tips for getting the most out of ADI **Start with capabilities.** Call `adi.get_capabilities` at the start of a session so your agent knows the trust tier, the enabled tools, and whether execution is available. **Permission is not the same as capability.** Your account may show you as approved with roles granted, but at t1 the server still has execution and warehouse access switched off. What your role permits and what the tier runs are two different things, so rely on `adi.get_capabilities` for what is actually available. **Invest time in improving the contract.** ADI enables authoring a contract based on the information that you provide. The more context and the more that you review and improve the contract, the better the resulting analysis based on the contract will be. Since the contract is generated by your own agent it is by definition non-deterministic so the more you invest in refining the contract, the more value you will see. **Validate every contract before you rely on it.** `adi.validate` catches errors that look fine on a manual read, including subtle ones that silently drop joins or rows. Treat a clean validation as the bar for a usable contract. At t1 this checks structure and meaning, not the contract against your real warehouse tables. **Ask in business language.** ADI's value is in compiling your intent into governed SQL. Writing SQL by hand bypasses the contract and loses provenance. **Read refusals carefully.** A refusal is not a dead end. It includes a reason, a code, and, where relevant, recovery information such as the metrics or group-bys that are allowed. **Use relative time windows.** Requests like "last quarter" or "last 30 days" adapt to the current date automatically, which is more reliable than hardcoded ranges. ## Next steps - Read the [Features page](https://docs.agentic-data.com/docs/starter-edition/features) for a detailed look at each MCP tool and the contract structure - See the [Beta Notes and Known Issues page](https://docs.agentic-data.com/docs/starter-edition/beta-test) for current limitations and practical guidance - Check the [Troubleshooting guide](https://docs.agentic-data.com/docs/reference/troubleshooting) if you run into issues --- # Starter Edition Features Starter Edition exposes ADI's control plane through a set of MCP tools that take you from discovering what the server allows, through authoring and validating a contract, to generating contract-governed SQL with full provenance. > [!NOTE] > **The Beta tool set (t1).** At t1 the enabled tools are `adi.get_capabilities`, `adi.get_authoring_spec`, `adi.generate_query`, and `adi.validate`. Execution (`adi.execute_sql`), warehouse introspection and profiling, and self-check replay are not part of t1; they belong to the execution tiers. The contract version is `1.0` and the query-request version is `1`. ## MCP tools ### adi.get_capabilities **Purpose:** Discover the active trust tier, the enabled features, and the tools you can call. **Returns:** the trust tier (for example `t0` or `t1`), a `features` object (including whether SQL execution is enabled), and the list of enabled tools. **When to use:** At the start of every session, before doing anything else. ### adi.get_authoring_spec **Purpose:** Fetch ADI's canonical contract schema and authoring guidance, including the mapping from a database engine to the SQL dialect the contract should declare. **When to use:** Before authoring a contract for your own data, so the contract you write matches the schema `adi.validate` checks against. ### adi.validate **Purpose:** Machine-validate a contract bundle against the canonical schema. **Parameters:** the contract `bundle` (the contract documents) and the `checks` to run (`structure`, `semantic`). **Returns:** whether the contract is valid, and, where it is not, path-pointed errors telling you exactly which field to fix. **When to use:** On every contract before you rely on it. Validation catches real errors that pass a manual review, including subtle ones that silently drop a join or a set of rows. > [!NOTE] > **What validation covers at t1.** At t1, `adi.validate` runs structural and semantic checks. Full warehouse-tier validation (checking the contract against your real schema, currency handling, and policies) needs server-side warehouse access, which is not part of t1; it belongs to the execution tiers. A clean result at t1 confirms the contract is well-formed, not that it matches your warehouse. ### adi.generate_query **Purpose:** Compile a structured request into contract-governed SQL. **Parameters:** a `query_request` (the metrics, group-bys, filters, ordering, and any top-N) and the `contract` it applies to, referenced either by its full documents or by a `contract_hash` returned from an earlier call. **Returns on success:** the generated `sql` and its `dialect`; `provenance` (metrics used, entities used, joins applied, group-bys, filters, and policies honoured); a plain-language `explanation`; and the row limit applied. **Returns on refusal:** a `refusal` object (see Refusals below). **When to use:** Every time a question needs answering. Guided by the Skill, your agent composes the structured request from the user's business-language question. Generation is deterministic: the same structured request returns byte-identical SQL. ### Schema and profiling tools (execution tiers) At the execution tiers, additional tools let the server read your warehouse: listing and describing tables, taking schema snapshots, and profiling tables and columns, along with `adi.replay_self_check` for replaying a contract's self-check assertions. These support contract authoring against a live warehouse. They are not part of the t1 Beta, where the server does not read your warehouse. ## The contract A contract is a bundle of YAML documents describing your data. Four are required: the top-level contract definition, the entities, the metrics, and the vocabulary (synonyms). Two are optional: policies (data classification and masking) and rules (currency handling, missing-data behaviour, and guardrails). Metrics are defined with one of four calculation types: `sum`, `count`, `count_distinct`, and `ratio` (a numerator over a denominator). Each metric declares which group-bys are allowed, which are disallowed, its default filters, its unit and currency handling, and how it is aggregated. To see a concrete example rather than working from the structure alone, ask your agent to show you the contract bundle that ships with the synthetic dataset (see Getting Started, Step 4). ## Governance features ### PII and data classification Sensitive columns are classified in the contract's policy document (for example `pii`, `sensitive`, `confidential`) with an action such as deny, mask, or redact. Grouping a metric by a disallowed column is refused before any data is touched, and safe alternatives are offered. Personal data does not reach the agent. ### Allowed and disallowed dimensions Each metric defines the group-bys that are valid for it. A request that groups by something outside that set is refused, with the allowed group-bys returned so the request can be corrected. ### Join safety The contract defines how entities relate. Guardrails can forbid many-to-many joins without a bridge table and require dimension uniqueness on a join key, so unsafe joins are refused rather than silently producing wrong numbers. ### Cardinality guardrails Grouping by a high-cardinality field can be refused, warned on, or capped, according to the contract's guardrails. Safe alternatives suggest a lower-cardinality dimension or a tighter filter. ### Read-only by default Guardrails restrict generated SQL to read verbs. Requests that would modify or delete data are refused. ## Refusals A refusal means the request was understood but cannot be fulfilled within the contract. Each refusal carries a `code`, a `message`, the `contract_path` it relates to, a `suggestion` where relevant, and a `details` object with recovery information (such as the available metrics or the allowed group-bys). Codes are lower_snake_case. | Code | Meaning | | -------------------------------- | --------------------------------------------------------------------------------------- | | `request_malformed` | The request shape or values are invalid | | `spec_version_unsupported` | The query-request version is not supported | | `metric_not_found` | The requested metric is not in the contract | | `metric_ambiguous` | The metric phrase matched more than one metric | | `entity_not_found` | An entity reference is unknown | | `field_not_in_contract` | A column is unknown on a known entity | | `dimension_not_allowed` | The group-by is not in the metric's allowed list | | `dimension_disallowed` | The group-by is explicitly blocked (for example an email column on the disallowed list) | | `policy_denied` | A policy restriction blocks the column (PII or governance) | | `join_path_absent` | The metrics cannot be safely joined (for example metrics on different base entities) | | `time_grain_unsupported` | The requested time grain is unavailable | | `aggregation_invalid` | The order-by field is not a metric or group-by | | `high_cardinality_refused` | The group-by would return too many rows | | `currency_normalization_missing` | A monetary metric has no currency conversion path | | `aggregation_fanout` | An additive metric would double-count across a to-many join | | `contract_invalid` | The contract itself cannot compile | | `contract_not_cached` | The `contract_hash` is unknown to the server; re-send the documents | | `intent_unparseable` | The request could not be interpreted | | `unsafe_operation_denied` | The requested operation is blocked | | `unsafe_sql_denied` | The SQL failed safety checks | A PII group-by is refused as `dimension_disallowed` when the column is on the metric's disallowed list, or as `policy_denied` when the column is an allowed group-by blocked by a policy action (deny, mask, or redact). Either way, personal data does not reach the agent. ## Provenance and contract reuse Every generated query returns a provenance chain: which metric definition was used, which entities and joins were involved, the group-bys and filters applied, the policies honoured, and a plain-language explanation. A `contract_hash` identifies a validated contract and can be reused on later `adi.generate_query` and `adi.validate` calls instead of resending the full documents. The Beta caches contracts for 24 hours. Because the hosted server runs multiple replicas with a per-replica cache, a reused hash can occasionally return `contract_not_cached`; when it does, re-send the contract documents and you will get the same hash back. At the execution tiers (t0 and t2), generated SQL also carries a **signature** in the form `adi-sql-v1:`, proving it was compiled from the contract, and signature-gated execution runs only signed SQL. The t1 Beta is generation-only and does not produce a signature. ## Supported platforms | Group | Platforms | | ------------------------------ | --------------------------- | | Dedicated plugins | Claude Code, Cursor, Codex | | Compatible plugins and skills | OpenClaw, Manus | **Compatible plugins and skills** covers OpenClaw, Manus, and any other coding agents that support either the Open Plugins Specification or the Agent Skills Specification. ADI is delivered as a plugin that bundles the Skills and an MCP server, both open standards, so any MCP-compatible coding agent can integrate with ADI, through the plugin or by installing the components individually. The same logical Skill content works across platforms with only minor metadata differences. --- # Beta Notes and Known Issues Practical notes for the Closed Beta: what to lean on, how the provided dataset behaves, and the current limitations. For setup and tips see Getting Started; for problem-solving see the [Troubleshooting guide](https://docs.agentic-data.com/docs/reference/troubleshooting). ADI's value in the Beta is turning a correct definition into a reusable, shared rule: once a metric is authored and validated, every session and every teammate working from that contract gets the same answer without re-deriving it. ## Working with the synthetic dataset The provided DuckDB dataset covers a fixed date range, so queries filtered to dates outside that range return valid but empty results. Prefer relative time windows, or remove the time filter to confirm data exists, then add it back. The dataset is deliberately messy (duplicate records, multiple currencies, mixed-case values, PII). That is intentional: it lets you see how the contract deduplicates, converts currency, and refuses PII group-bys. The provided contract already handles these, so lean on it rather than reworking the data by hand. ## Current limitations A short, honest list of what to expect while the Beta matures. These are being worked on. - **You run the generated SQL yourself, and a validated query can still fail when you run it.** At t1 the SQL runs in your own environment. A clean validation confirms the contract is well-formed and the SQL was compiled from it; it does not guarantee the query runs, since an underlying column type can still cause a failure at execution. - **A clean `adi.validate` at t1 checks structure and meaning, not your real tables.** Validation does not reach your warehouse at t1, so a clean result does not confirm the contract matches your actual schema. - **Multi-metric requests** are supported when the metrics share a base entity; requests spanning unrelated base entities are refused (`join_path_absent`). - **Some measures cannot yet be expressed as governed metrics** (for example medians and percentiles, or figures held in encoded column types). Where a figure has to be composed outside the contract, that is flagged. - **Query-request filter operators are lowercase.** In the request your agent sends, use `in`, not `IN`; an uppercase operator is refused as `request_malformed`. The contract's own `default_filters` use SQL-style uppercase operators, which is a separate authoring schema. - **Absolute date ranges are inclusive at both ends.** `start` and `end` each cover their full calendar day, so a range ending `2026-06-30` includes all of the 30th. To exclude the final day, for example to get a clean month boundary, set `end` to the day before, or add a separate `<` filter on the time column rather than relying on the range alone. --- # Enterprise Edition Overview Enterprise Edition brings ADI's control plane to teams using copilots and agents on cloud data and analytics platforms. It adds a semantic and control layer that improves the governance, accuracy, and consistency of the analytics those tools produce, delivered as a native app that runs inside your own warehouse. ## Who it is for Enterprise Edition is built for startups and enterprises that already use copilots and agents for data analytics and want to trust what those tools do with the data. That includes: - **Teams adopting agents on the warehouse** who need governance built so the platform enforces it, not policy on paper - **Organisations enabling self-serve analytics** who want business users to ask questions through an agent without losing control of what the metrics mean - **Data teams standardising definitions** across financial, operational, marketplace, or other data domains ## How it is delivered Enterprise Edition runs as a native app inside your own cloud data warehouse. It connects to the data already there, builds its four-layer understanding, and enforces the contract above the copilots and agents your team uses. Your data stays in your warehouse, and ADI extends, rather than replaces, your existing catalogue and governance. Where Starter Edition works within a single developer's coding agent, Enterprise Edition operates at the team and organisation level, with stricter authentication, security, and data governance enforcement, and a Slack-based governance process for reviewing and approving changes. ## How it differs from Starter Edition | Dimension | Starter Edition | Enterprise Edition | | ---------- | ------------------------------------ | --------------------------------------------------------------- | | Built for | Individual developers and analysts | Teams and organisations | | Focus | Coding agents and IDEs | Cloud data and analytics platforms | | Delivery | Plugin bundling the Skills and MCP server | Native app inside your own warehouse | | Semantics | Basic semantics and rules | Full and complex semantics, rules, and analytical processing | | Governance | Standard authentication and security | Strictly enforced authentication, security, and data governance | The core four-layer architecture and control-plane principle are the same across both editions. Enterprise Edition adds the depth of semantic modelling, the breadth of integrations, and the rigour of governance that production team environments require. ## Platform integrations **Data platforms (available now):** Snowflake, Databricks **Data platforms (coming soon):** Google BigQuery, Amazon Redshift **Interoperability:** The contract's analytical model can be output to MetricFlow, and two-way Open Semantic Interchange (OSI) compatibility is planned for a future version. See the Features page for detail. ## Current status Enterprise Edition is in limited Alpha. Request early access at [agentic-data.com/access](https://agentic-data.com/access). Early partners get direct access to the team and help to shape what gets built next. --- # Enterprise Edition Features Enterprise Edition builds on the same four-layer architecture and control-plane principle as Starter Edition, with deeper semantic modelling, broader integrations, and stricter governance enforcement for team and production use. ## Full semantic modelling Enterprise Edition supports the full complexity of real-world data environments: - **Complex entity relationships** across multiple data domains, including many-to-many relationships with bridge tables - **Advanced metric definitions** with compound calculations, currency handling, and time-series aggregation rules - **Multi-domain semantic models** spanning financial, operational, marketplace, and other data types - **Schema change detection** that updates the semantic model when source data structures change, keeping enforcement consistent across downstream consumers Where Starter Edition provides basic semantics and rules for individual developer workflows, Enterprise Edition handles the full range of semantic complexity that production environments demand. ## Warehouse-native deployment Enterprise Edition runs as a native app inside your own cloud data warehouse: | Platform | Status | |----------|--------| | Snowflake | Available now | | Databricks | Available now | | Google BigQuery | Coming soon | | Amazon Redshift | Coming soon | ADI inspects the warehouse, profiles the tables, and builds its four-layer understanding from the data already there. Your data stays in your warehouse, and ADI extends your existing catalogue and governance rather than replacing them. ## Governance and security Enterprise Edition enforces governance at the platform level, with stricter controls than Starter Edition: - **Authentication and access control** with enterprise-grade security - **Data governance policies** that define what data can be queried, by whom, and under what conditions - **PII protection** enforced before data reaches any agent or user - **Audit trails** tracking every query, every governance check, and every execution decision - **Consumption contracts** that define the valid query surface and refuse anything outside it Enterprise Edition is designed so governance is not optional or configurable at the agent level: the contract defines the boundaries, and the platform enforces them, regardless of how the consuming copilot or agent is configured. ## Human-in-the-loop governance Changes to the semantics and the contract are explicit, versioned, and reviewable. Enterprise Edition adds a Slack-based governance process, so a proposed change can be reviewed and approved in the flow of work before it takes effect. ## User interface Enterprise Edition provides a user interface for: - Configuring data source connections - Reviewing and refining the semantic model ADI builds - Monitoring enforcement and query activity - Managing governance policies and consumption contracts - Reviewing the audit trail of queries and governance decisions The interface is the primary control point for Enterprise Edition, in contrast to Starter Edition where the interaction happens through the coding agent. ## Interoperability The analytical model defined in the contract can be output to MetricFlow as an output sink, so the metric definitions are usable in existing downstream workflows. ADI is also working towards two-way compatibility with the Open Semantic Interchange (OSI) standard, importing and exporting OSI-conformant semantic models. ## Cross-domain data support Enterprise Edition works across data domains: financial data, operational data, marketplace data, and anything else in your warehouse. The four-layer architecture applies the same way regardless of the business domain. A contract for financial metrics follows the same structural principles as a contract for operational measures. --- # Frequently Asked Questions ## General ### What is Agentic Data Intelligence? ADI is the control plane for AI data analytics. It sits as a thin layer between agents and your data, generating a machine-readable model of what your data means and an enforceable contract that constrains how AI agents use it. The result is consistent, trustworthy analytics above the stack you already run. ### How is ADI different from a data copilot? Copilots write SQL quickly from a natural-language question but cannot tell you whether the answer is right, and the same question can return different numbers. ADI builds an explicit model of what your data means first, then holds every query to it. Every query is checked against the contract, and within a shared contract the same question yields the same answer. Keep the copilots and agents you already use: ADI works above them, constraining how they query and holding them to what the metrics mean. ### What editions are available? Two editions, each for a different audience: - **Starter Edition** for individual developers, data engineers, and analysts adding semantic and control functionality to coding agents and IDEs - **Enterprise Edition** for teams adding a semantic and control layer to the copilots and agents they run on cloud data and analytics platforms ### What is the current product status? Starter Edition is entering Closed Beta, and Enterprise Edition is in limited Alpha. Request early access at [agentic-data.com/access](https://agentic-data.com/access). ### What data domains does ADI support? ADI is domain-agnostic. It works with financial data, operational data, marketplace data, and even blockchain data. The four-layer architecture applies the same way regardless of business domain. ### Does ADI see or store my data? No. ADI never sees your underlying data. The contract is generated from schema and context, and analysis runs in your own environment. You hold the data and the model; ADI holds the meaning and the rules. ## Starter Edition ### Which coding agents does Starter Edition support? Claude Code, Cursor, and Codex install via a dedicated plugin. OpenClaw, Manus, and any other coding agents that support either the Open Plugins Specification or the Agent Skills Specification are also supported. Any MCP-compatible client can integrate with ADI. ### Do I need to write SQL? No. You ask in business language and your agent, guided by the Skill, compiles the request into contract-governed SQL. Writing SQL by hand bypasses the contract and loses provenance. ### How does a contract get created? You author it for your own data (with your agent, using ADI's authoring spec) and validate it with `adi.validate` before use, or you start with the ready-made contract that ships with the provided synthetic dataset. ### What happens when ADI cannot answer a question? ADI refuses the request and tells you why. Refusals include a code, a plain-language reason, and recovery information such as the metrics or group-bys that are allowed. A refusal is not a dead end; it is guidance toward a valid request. ### Does a generated query carry a signature? Not in the Beta. The Beta runs at t1, which is generation-only: a generated query carries provenance (which metric, entities, joins, filters, and policies were used) but no signature. The signature (in the form `adi-sql-v1:`) and signature-gated execution, where only contract-compiled SQL runs through the verified path, are capabilities of the execution tiers (t0 and t2). ## Enterprise Edition ### How does Enterprise Edition connect to my data? Enterprise Edition runs as a native app inside your own cloud data warehouse. Snowflake and Databricks are supported now, with Google BigQuery and Amazon Redshift coming soon. Your data stays in your warehouse. ### Does ADI replace my catalogue, governance, or transformation tools? No. ADI extends your existing catalogue and governance rather than replacing them. It adds the layer of meaning and enforcement that no other tool owns, above the stack you already run. ### Can ADI's output be used in existing downstream tools? Yes. The contract's analytical model can be output to MetricFlow, so its metric definitions are usable in downstream tools, and ADI is working towards two-way Open Semantic Interchange (OSI) compatibility in a future version. ## Security and governance ### How does ADI protect personal data? Sensitive columns are classified in the contract's policy document, and requests that would expose them (for example grouping by an email address) are refused before any data is touched. Personal data does not reach the agent. Safe alternatives such as counts, cohorts, or aggregated views are offered. ### Can an agent reach data outside the contract? The contract, not the agent's prompt, decides what can be queried. When your agent asks for something outside the contract, ADI refuses it as the SQL is generated: out-of-contract requests, unsafe joins, and disallowed group-bys are all refused, and generated SQL is restricted to read operations. Enforcement at execution, where only signed SQL runs, is a capability of the execution tiers (t0 and t2). ### Is there provenance and an audit trail? Every generated query returns provenance: which metric was used, which entities and joins were involved, the group-bys and filters applied, and the policies honoured. Enterprise Edition adds full audit trails across queries and governance decisions. --- # Glossary Key terms used throughout the ADI documentation. ## Product terms **ADI (Agentic Data Intelligence)** The control plane for AI data analytics. A thin layer between agents and your data that generates a machine-readable model of what your data means and an enforceable contract constraining how AI agents use it. **Starter Edition (SE)** The ADI edition for individual developers, data engineers, and analysts. Delivered as a plugin bundling the Skills and MCP server, for coding agents and IDEs. **Enterprise Edition (EE)** The ADI edition for teams and organisations. Delivered as a native app inside the customer's own cloud data warehouse. **Control plane** The role ADI plays: it does not query the data itself, it governs how agents and copilots query, holding them to the contract. **Contract** A structured definition of what data can be queried, how it should be measured, and what governance rules apply. The single source of truth for all agents and queries. Also called a "consumption contract". **Contract bundle** The set of YAML documents that make up a contract: the contract definition, entities, metrics, and vocabulary (required), plus policies and rules (optional). **Trust tier** The level at which a Starter Edition instance runs, reflecting how much of the workflow the platform runs on your behalf. The Beta runs at t1 (generation and validation only). t0 (self-hosted) and t2 (fully hosted with credentials) are the execution tiers, planned for future releases. ## Architecture terms **Data Asset Layer (DAL)** The first layer. What data physically exists and how it is structured: schemas, tables, columns, keys, and relationships. **Business Model Layer (BML)** The second layer. What the business cares about: entities, events, and the relationships between them. Maps physical data to business concepts. **Analytical Model Layer (AML)** The third layer. How the business can be measured: dimensions, metrics, and the rules for calculation and aggregation. Can be output to MetricFlow as an output sink. **Consumption Contract Layer (CCL)** The fourth layer. Defines how users and agents are allowed to ask questions: supported intents, default behaviours, and guardrails. The system-level enforcement of correctness. **Four-layer architecture** ADI's approach to building understanding of data, each layer adding meaning on top of the one below: Data Asset Layer, Business Model Layer, Analytical Model Layer, Consumption Contract Layer. **Semantic model** The complete understanding ADI builds of your data: what it is, what it means, how it can be measured, and how it can be queried. Encompasses all four layers. ## Technical terms **MCP (Model Context Protocol)** An open standard for connecting AI agents to external tools and data sources. ADI exposes its tools as an MCP server. **SKILL.md** A file following the Agent Skills Specification that contains instructions for an AI agent: which tools to call, in what order, how to author and validate a contract, and how to handle responses. **Plugin** A bundle of the Skills, the MCP server, and potentially other elements, so your agent can get started without installing each individually. The plugin is the recommended way to install Starter Edition, with dedicated plugins for Claude Code, Cursor, and Codex; see Getting Started for the install commands. **FastMCP** The MCP server framework ADI uses to expose its tools. **adi.get_capabilities** The tool that reports the active trust tier, the enabled features (including whether execution is available), and the tools you can call. **adi.get_authoring_spec** The tool that returns ADI's canonical contract schema and authoring guidance, used when authoring a contract for your own data. **adi.validate** The tool that machine-validates a contract bundle against the canonical schema, returning path-pointed errors for anything that needs fixing. At t1 it runs structural and semantic checks; warehouse-tier validation needs the execution tiers. **adi.generate_query** The tool that compiles a structured request into contract-governed SQL, returning the SQL, its provenance, and a plain-language explanation, or a refusal. **Recommended workflow** Discover capabilities (`adi.get_capabilities`), author and validate a contract (`adi.get_authoring_spec`, `adi.validate`) or load a provided one, then generate governed SQL (`adi.generate_query`). At t1 you run the generated SQL in your own environment; at the execution tiers the server can run it directly. ## Governance terms **Refusal** ADI's response when a request asks for something outside the contract. Carries a code, a message, the relevant contract path, and recovery information (such as the allowed metrics or group-bys). A refusal is expected control flow, not an error. Codes are lower_snake_case and include `request_malformed`, `metric_not_found`, `dimension_not_allowed`, `dimension_disallowed`, `policy_denied`, `join_path_absent`, `high_cardinality_refused`, and `contract_not_cached`; see the Features page for the full set. **Safe alternatives** Recovery information returned with a refusal: the metrics, group-bys, or related requests the contract can answer. **Policy classification** The labelling of sensitive columns in the contract's policy document (for example `pii`, `sensitive`, `confidential`) with an action such as deny, mask, or redact. Enforced before data reaches any agent. **Signature** A token in the form `adi-sql-v1:` proving a generated query was compiled from the contract. It is produced at the execution tiers (t0 and t2), where it gates execution so only contract-compiled SQL runs. The t1 Beta is generation-only and does not produce a signature. **contract_hash** A hash identifying a validated contract. Can be reused on later `adi.generate_query` and `adi.validate` calls instead of resending the full contract documents; the Beta caches contracts for 24 hours. **Provenance** The traceable chain from request to result: the metric used, the entities and joins involved, the group-bys and filters applied, the policies honoured, and a plain-language explanation. Returned on every generated query. ## Data terms **Metric** A defined measurement in the contract (for example order count, total revenue). Metrics have a fixed calculation type (sum, count, count_distinct, or ratio) and are consistent across all agents and sessions. **Dimension** A category for grouping or filtering metrics (for example country, product). The contract defines which dimensions are allowed for each metric. **Entity** A business object in the data model (for example organisations, users, orders). Entities have relationships defined in the Business Model Layer. **Vocabulary** Synonym lists for metrics and dimensions, included in the contract to help agents match natural-language terms to the correct contract fields. ## Workflow terms **Human-in-the-loop** ADI's operating model where humans stay in control. Agents handle routine work; humans approve changes to the semantics and the contract and define what matters to the business. Enterprise Edition adds a Slack-based governance process. **Agentic loop** ADI's continuous cycle: sense changes in data and schema, update understanding, answer questions within boundaries, enforce the contract, and learn from reviewed feedback. --- # Troubleshooting This guide covers common issues when working with ADI Starter Edition and how to resolve them. ## Connection issues ### MCP tools do not appear in your agent **Symptoms:** No `adi.*` tools are listed. The agent has no access to ADI. **Check these in order:** 1. **The endpoint and connection settings** match what you were issued on acceptance, and you are signed in to your Zitadel account with your access approved. 2. **The file location** for your MCP config is in the root of the folder you have open in your client, not a subfolder or parent directory. 3. **The trust prompt** in Claude Code requires you to approve a new MCP server when it first appears. If you missed it, close and reopen the project folder. **If tools still do not appear:** - Fully close and reopen your agent (not just the file) - Confirm the endpoint is reachable from your network - Discover capabilities with `adi.get_capabilities` once connected, to confirm which tools are enabled at your trust tier > [!NOTE] > **Connection and authentication.** The server is reached over streamable HTTP at the endpoint provided to you on acceptance. Authentication is required: you sign in with, or create, a Zitadel account on first connection. There is no API key. If your access is still being approved, the tools report a pending status until it is active. ### Python SSL certificate failure **Symptoms:** Python's `urllib` raises `SSL: CERTIFICATE_VERIFY_FAILED`. **Cause:** Some Python builds do not include the necessary intermediate certificates. **Workaround:** Use the `requests` library (which uses `certifi`) or `curl` instead of Python's built-in `urllib`. ## Query issues ### Queries return zero results **Symptoms:** A valid request with a known metric returns 0 rows. **Most common cause:** The time window falls outside the range of your data. For example, if your dataset starts in a given year, a request filtered to an earlier year returns zero results legitimately. **Solutions:** 1. Use relative time windows ("last quarter", "this year", "last 30 days") rather than fixed dates 2. Remove the time filter to confirm data exists, then add it back with the correct range 3. Confirm the metric name is in the contract ### Rate limiting causes empty responses **Symptoms:** First requests work, then subsequent ones return empty or null results, with no rate-limit error shown. **Cause:** Rapid sequential calls can exceed the server's rate limit, and the server may return an empty body rather than a standard error. **Solutions:** 1. Add a short delay between sequential calls 2. Wait a second or two before retrying a failed call 3. Run analytics in logical groups with pauses between them ## Refusal handling ### A request is refused with an unexpected code **Symptoms:** A request is correctly refused, but the code does not match what you expected. **Common refusal codes:** | Code | Meaning | | ----------------------- | --------------------------------------------------------------------------------------- | | `metric_not_found` | The requested metric is not in the contract | | `dimension_not_allowed` | The group-by is not in the metric's allowed list | | `dimension_disallowed` | The group-by is explicitly blocked (for example an email column on the disallowed list) | | `policy_denied` | A policy restriction blocks the column (PII or governance) | | `join_path_absent` | The metrics cannot be safely joined (for example metrics on different base entities) | | `request_malformed` | The request shape or values are invalid | | `contract_not_cached` | The `contract_hash` is unknown to the server; re-send the documents | The full set is on the [Features page](https://docs.agentic-data.com/docs/starter-edition/features). A PII group-by refuses as `dimension_disallowed` when the column is on the metric's disallowed list, or as `policy_denied` when it is an allowed group-by blocked by a policy action. Each refusal carries recovery information in its `details` (such as the available metrics or the allowed group-bys); use it to adjust the request. ### A contract fails validation **Symptoms:** `adi.validate` reports errors on a contract that looks correct. **Cause:** Small schema mismatches are easy to miss on a manual read, and some are subtle enough to silently drop a join or a set of rows. **Action:** Read the path-pointed errors `adi.validate` returns and fix each at the field it points to, rather than working around them. Re-validate until the contract is clean before relying on it. > [!NOTE] > **DuckDB dialect.** When authoring a contract for DuckDB data, declare the contract's SQL dialect as `postgres` (per ADI's engine-to-dialect mapping). There is no `duckdb` SQL dialect, so declaring one will fail validation. ## Running the generated SQL ### A validated query fails when you run it **Symptoms:** `adi.generate_query` returned validated SQL, but the query fails when you run it in your own environment. **Cause:** At t1 you run the SQL yourself. A clean validation confirms the SQL was compiled from the contract; it does not guarantee the query runs, since an underlying column type can still cause a failure at execution. **Action:** Check the underlying column types involved. Where a figure cannot be computed within the contract, compose it outside and flag it. ### Generated SQL is rejected by Snowflake **Symptoms:** The generated SQL runs on Postgres or DuckDB, but Snowflake raises `invalid identifier`, or a boolean predicate does not match. **Cause:** The compiler emits SQL shaped for the `engine` and `sql_dialect` declared in the contract's `datasource` block, not for whichever warehouse the SQL is actually run against. ADI's `engine_dialect_map` maps `duckdb` to the `postgres` dialect, so a contract declaring `engine: duckdb` (or `engine: postgres`) emits Postgres-shaped SQL: lower-case double-quoted identifiers and `is_active = 1` for booleans. Postgres and DuckDB fold that correctly; Snowflake does not, so the same SQL fails there. **Action:** Declare `engine: snowflake` and `sql_dialect: snowflake` in the contract's `datasource` block when the target warehouse is Snowflake. With that declared, the compiler emits Snowflake-shaped SQL: upper-case double-quoted identifiers and `= TRUE` for booleans. Do not strip the double quotes from the identifiers: they preserve the exact case Snowflake's storage uses, and removing them would break a genuinely mixed-case column. ### A filter is refused as request_malformed **Symptoms:** A query request with a filter operator such as `IN` is refused as `request_malformed`. **Cause:** Query-request filter operators are lowercase (`in`, `not_in`, `between`, and so on). Uppercase operators are rejected. The contract's own `default_filters` use SQL-style uppercase operators, which is a separate authoring schema, so the two can look inconsistent. **Action:** Use lowercase operators in the query request. ### A reused contract returns contract_not_cached **Symptoms:** A `generate_query` or `validate` call that reuses a `contract_hash` returns `contract_not_cached`, even though the contract validated earlier. **Cause:** The hosted server runs multiple replicas with a per-replica cache, so a hash cached on one replica can miss on another. This is expected. **Action:** Re-send the contract documents inline; you will get the same hash back. The Beta caches contracts for 24 hours. ## Quick reference | Task | Tool | Key detail | | ----------------------------- | ------------------------ | ------------------------------------------------- | | Discover trust tier and tools | `adi.get_capabilities` | Call at the start of every session | | Fetch the contract schema | `adi.get_authoring_spec` | Use before authoring a contract | | Validate a contract | `adi.validate` | Fix the path-pointed errors it returns | | Generate governed SQL | `adi.generate_query` | Ask in business language; never write SQL by hand | | Problem | Most likely cause | First thing to check | | ------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------- | | Tools not appearing | Connection or sign-in | Endpoint, Zitadel sign-in (access approved), trust prompt; discover with `adi.get_capabilities` | | Empty results | Time window | Check the date range of your data | | Unexpected refusal code | Out-of-contract request | Read `details` for recovery; full code set on the Features page | | Contract fails validation | Schema mismatch | Read the path-pointed errors; check the SQL dialect | | Query fails when you run it | Underlying column type | You run the SQL yourself at t1; check the column types | | SQL rejected by Snowflake | Contract declared for a different dialect | Confirm `datasource.engine`/`sql_dialect` is `snowflake`; do not strip the quotes | | Filter refused as `request_malformed` | Uppercase operator | Use lowercase operators (`in`) in the query request | | `contract_not_cached` on reuse | Per-replica cache miss | Re-send the contract documents; the same hash returns | --- # Legal and Data Use This page summarises the terms, licences, and data-handling points that apply when you use ADI Starter Edition in the Beta. It is a plain-language summary and points to the documents that govern each area; those documents take precedence. ## General **Terms and privacy.** Use of Starter Edition is governed by our [Terms of Service](https://agentic-data.com/terms) and [Privacy Policy](https://agentic-data.com/privacy). You accept these terms explicitly when you create your Zitadel account for authentication (see below). **Skills and Plugins.** The ADI Skills and Plugins are provided through a GitHub repo and are installed directly into your agent. Each repository states its own licence. In the future they may also be listed on various official and community marketplaces and listings. **Identity and authentication.** Identity and authentication are provided by Zitadel, a Swiss-headquartered identity and authentication platform, and ADI uses it with data residency in Switzerland. You sign in with, or create, a Zitadel account when you connect. You can find more information about Zitadel here: - Website: [zitadel.com](https://zitadel.com) - Privacy Policy: [zitadel.com/docs/legal/policies/privacy-policy](https://zitadel.com/docs/legal/policies/privacy-policy) - Trust Centre: [zitadel.com/trust](https://zitadel.com/trust) ## AI use You use ADI through your own coding agent and the LLM(s) that your agent runs. The LLM steps happen on your side, under your control, so your settings and your model provider's terms are the ones that apply. Because of this, we strongly advise that you review your agent's data-protection, privacy, and model-training settings before you start, and make sure any training or data-sharing options are set the way you intend. Do not provide any personal, confidential, or sensitive data during the process of using ADI. You are solely responsible for the use of your data with your agent and LLM(s). By design, ADI does not use a language model to author your contract or to generate your SQL in Starter Edition. Your agent does the LLM work: it reads ADI's authoring specification and drafts the contract, and it turns your question into a structured request. ADI then validates the contract and compiles the request into SQL deterministically, without a language model, so the same request always produces the same SQL. ADI never sees your underlying data. The contract is built from schema and context, and at the Beta tier (t1) the generated SQL runs in your own environment. For more detail, see our [AI Notice](https://agentic-data.com/ai-notice).