Skip to content

Atlas rule-authoring agent

Deploy the packaged Atlas AI skills and agent that help authors write SHACL data quality rules from plain language across the validation journey (Consistency, edge existence, uniqueness, time series, conditional and chained conditional logic). Definitions ship inside the cognite-data-quality package — install from PyPI, then call the deploy helper. No separate clone of this repository is required.

Flows client tools such as submit_rule and test_rules stay with the Data Quality app at chat time. This package deploys only the Atlas skill content, agent instructions, skill attachments, and runtime. Agent tools draft and test only — they do not Publish RuleSet or Data Product versions. For the in-app Publish and multi-view quality.rules contract, see Editing Data Products and RuleSets in Flows apps.

When to use it

Use this when your project uses the Data Quality Flows chat experience and you want the rule-authoring agent kept in sync with the package release.

Example prompts (each loads the matching skill):

  • Consistency: “When a session has a time series, that link must point to a time series that actually exists.”
  • Edge existence: “Every work order must have at least one work item edge.”
  • Uniqueness: “Make sure work order numbers are unique across the estate.”
  • Time series: “Pressure sensors must have at least 50 datapoints in the last hour.”
  • Conditional: “If status is completed and there is no end time, emit a NeedsReview inference.”
  • Chained: “First tag completed work orders, then escalate when end time is missing — use ordered dependent rules.”

What ships in the package

Resource External ID Role
Skill dq-shacl-direct-relation-consistency Stub sh:node + SPARQL for forward direct-relation Consistency
Skill dq-shacl-edge-existence dqs:edgeExistenceConstraint for typed-edge cardinality
Skill dq-shacl-uniqueness dqs:uniquenessConstraint / dqs:unique
Skill dq-shacl-timeseries-quality cdf_sdk datapoint windows
Skill dq-shacl-conditional-af SHACL-AF RuleEngineResult inferences
Skill dq-shacl-chained-conditional Ordered sh:order / dqs:dependsOn chains
Agent DQ_AGENT_0001 Rule generator (runtime 2.x) with the skills attached

Source files live under cognite_data_quality/agents/ in the installed wheel. Upgrading cognite-data-quality and re-running deploy refreshes CDF to match.

Prerequisites

  • A Cognite project with Atlas AI Skills and Agents APIs available (beta cdf-version header; the deploy helper sets this for you).
  • Credentials that can create or update skills and agents in that project.
  • The Data Quality Flows (or equivalent) app that registers chat-time client tools (submit_rule, test_rules, and related helpers). Without those tools, the agent can draft patterns but cannot submit or test rules in the app.

Deploy from the package

from cognite_data_quality import deploy_atlas_rule_authoring, load_cognite_client_from_toml

client = load_cognite_client_from_toml("config.toml")
result = deploy_atlas_rule_authoring(client)
# result: skills, agents, dry_run, verified

What this does:

  1. Loads definitions from the installed wheel (cognite_data_quality/agents/).
  2. Temporarily detaches skills from the agent (CDF rejects skill upserts while attached).
  3. Upserts all packaged skills, then restores the agent with runtime 2.x and skills attached.
  4. Verifies remote content (Consistency skill still includes the sh:node pattern; agent lists all skills).

Dry run without writing to CDF:

deploy_atlas_rule_authoring(client, dry_run=True, verify=False)

Optional arguments:

Argument Default Meaning
agent_external_id DQ_AGENT_0001 Atlas agent external ID to upsert
skill_external_ids all packaged journey skills Skill IDs to deploy
dry_run False Print planned upserts only
verify True Retrieve remote resources after deploy and check content

Opt in during infrastructure deploy

Add to settings.yaml:

atlas_rule_authoring:
  enabled: true
  agent_external_id: DQ_AGENT_0001
  verify: true

Or pass the flag explicitly:

from cognite_data_quality import deploy_validation_infrastructure

deploy_validation_infrastructure(
    client=client,
    settings_path=settings_path,
    deploy_atlas_rule_authoring=True,
)

Default is off so SHACL-only projects do not overwrite an Atlas agent. When enabled, deploy_validation_infrastructure returns an atlas_rule_authoring key alongside the usual function and workflow results.

Authoring rules in chat

After deploy, open the Data Quality Flows chat with agent DQ_AGENT_0001 (or the external ID you configured). Ask in plain language for the mode you need. The agent should load the matching skill, draft Turtle, deliver with submit_rule (draft only — never publish a RuleSet or Data Product version), then call test_rules and iterate on failures.

Consistency (direct relations)

For target existence / typing on a relation, the agent should:

  1. Load dq-shacl-direct-relation-consistency.
  2. Draft Turtle with a stub target shape (sh:node + sh:targetClass) and SPARQL under the same property.

Required Turtle shape (summary)

Every Consistency existence / type check on a forward direct relation must include:

  1. A stub sh:NodeShape with sh:targetClass for the target view.
  2. Stub names like *ExistenceShape — never the bare view id alone when that id is reserved in CDF (for example prefer TimeSeriesExistenceShape over TimeSeries). These stubs must not cause the engine to bind this RuleSet onto the neighbour view; focus binding skips *ExistenceShape and other structural neighbour stubs (Engine focus binding).
  3. On the source property shape: sh:path + sh:node pointing at that stub.
  4. SPARQL (FILTER NOT EXISTS { ?target a TargetView }) under the same property.
  5. The real target view external ID from schema (often CogniteTimeSeries), not only the property local name.

Engine contract detail and a full example: SHACL and CDF data models — Auto-load. Industrial context: Graph consistency.

Boundaries

  • Client tools are not stored on the Atlas agent resource; the Flows app registers them at chat time.
  • Nested sh:node that decomposes {space, externalId} paths is not supported for auto-load.
  • sh:class on a property shape does not trigger auto-load — use stub sh:node + sh:targetClass.
  • Unsupported SHACL constructs for this authoring path include sh:rule, sh:qualifiedValueShape, sh:closed, and sh:if / then / else.