@oxy-hq/cli 0.7.0 → 0.9.0

package/skills/oxy-agents/templates/agentic-template.yml

@@ -0,0 +1,141 @@
+# Oxy `.agentic.yml` template: an analytics agent over the semantic model.
+#
+# Save as <name>.agentic.yml (not .yaml) anywhere in the workspace, but not
+# under a dot-directory, build/, dist/, target/ or node_modules/, and with no
+# `.test.` in the file name; those paths are not deployed.
+#
+# Check the shape offline:   oxyc validate --file <path>
+# First real check is a run: oxy agentic run <path> -q "<question>"
+#
+# Every key is optional. Unknown keys, at any level, are ignored without a
+# warning by the runtime and by both validators, so spell them exactly.
+
+# -- Global instructions -----------------------------------------------------
+# Added to the system prompt of every LLM state. Put the persona, business
+# conventions and the views/topics to prefer here; per-state additions go
+# under `states:` and are appended, not substituted.
+instructions: |
+  You are a revenue analytics assistant for Acme Corp.
+  Report currency in USD and dates as ISO 8601.
+  "Customer" means the `customers` view, not `users` (which counts seats).
+  Prefer measures from the semantic model over hand-written aggregations.
+
+# IANA timezone for "today", "yesterday", "last week". Falls back to the
+# `timezone:` in config.yml, then UTC. An invalid name fails the run.
+timezone: America/New_York
+
+# -- Connections ---------------------------------------------------------------
+# Names from config.yml `databases:`. The agent can query these PLUS every
+# database its context files reference (a view's `datasource`, a verified
+# query's `database:`, an automation task's `database:`). There is no fallback
+# to every database in config.yml: with none at all the run fails with
+# "no databases configured".
+databases:
+  - warehouse
+
+# -- Context -------------------------------------------------------------------
+# Globs relative to THIS file's directory, bucketed by file name:
+#   *.view.yml, *.topic.yml               semantic catalog
+#   *.sql with a /* oxy: ... */ header    verified query: found by the
+#                                         search_automations tool, run verbatim
+#   *.sql without that header             SQL style examples for `solving`
+#   *.md                                  notes for `clarifying`/`interpreting`
+#   *.automation.yml, *.procedure.yml     automations the agent may pick and run
+# Anything else is ignored.
+context:
+  - ./semantics/**/*.view.yml
+  - ./semantics/**/*.topic.yml
+  - ./verified_queries/*.sql
+  - ./docs/glossary.md
+  - ./automations/*.automation.yml
+
+# -- Model ---------------------------------------------------------------------
+# `ref` must equal a `name:` under config.yml `models:`; vendor, API key (a
+# workspace secret in the cloud) and base URL come from that entry. With
+# neither `ref` nor `model`, the first model in config.yml is used.
+# `model` fields here and under `states:` are provider model IDs, not
+# config.yml names.
+llm:
+  ref: claude
+  # Leave max_tokens unset unless you need a hard cap: unset, it is sized from
+  # the thinking setting. A value you set is used as-is.
+  # max_tokens: 8192
+  #
+  # Replaces the model AND the thinking setting in every state while the user
+  # has "extended thinking" switched on. Without this block the toggle does
+  # nothing.
+  extended_thinking:
+    model: claude-opus-4-8
+    thinking:
+      effort: high
+
+# -- Thinking --------------------------------------------------------------------
+# A global value REPLACES every state's built-in default (solving: adaptive,
+# all others: disabled), so prefer setting it per state below.
+# Forms: adaptive | disabled | effort:<level> | {effort: <level>} |
+#        {budget_tokens: N} (Claude 4.6 and earlier; converted on newer models)
+# Levels: low | medium | high | xhigh | max. Never `false`.
+# thinking: adaptive
+
+# -- Per-state overrides ---------------------------------------------------------
+# Honoured keys: clarifying, specifying, solving, interpreting. (`executing`
+# has no LLM; any other key is ignored silently.)
+# Fields: instructions, thinking, model (same provider as `llm:`), and
+# max_retries = tool-call rounds per visit before the run pauses to ask the
+# user whether to continue (clarifying has a fixed limit and ignores it).
+states:
+  clarifying:
+    instructions: |
+      "Last quarter" means the most recent completed fiscal quarter.
+      "MRR" is the `monthly_recurring_revenue` measure on the `revenue` view.
+    model: claude-haiku-4-5
+  specifying:
+    max_retries: 8
+  solving:
+    # Runs only when the semantic model could not compile the question, so
+    # never put guidance every answer needs here.
+    instructions: Prefer CTEs over subqueries; alias every aggregate.
+    thinking:
+      effort: high
+    max_retries: 4
+  interpreting:
+    thinking: disabled
+
+# -- Result checks (optional) ----------------------------------------------------
+# Omit the whole section to run the 15 default checks with default thresholds.
+# When present it REPLACES that set: only the rules listed here (and not
+# `enabled: false`) run, and a stage with no list is not checked at all.
+# This is the full default set with two thresholds tuned.
+validation:
+  rules:
+    specified:
+      - name: metric_resolves
+      - name: join_key_exists
+      - name: filter_unambiguous
+    solvable:
+      - name: sql_syntax
+      - name: tables_exist_in_catalog
+      - name: spec_tables_present
+      - name: column_refs_valid
+      - name: timeseries_order_by_check
+    solved:
+      - name: non_empty
+      - name: truncation_warning
+      - name: no_nan_inf
+      - name: outlier_detection
+        threshold_sigma: 4.0
+        min_rows: 6
+      - name: null_ratio_check
+        threshold: 0.3
+      - name: duplicate_row_check
+      - name: freshness_check
+
+# -- External semantic engine (optional) -----------------------------------------
+# Routes queries through Cube or Looker before Oxy's own semantic model. The
+# engine is pinged when a run starts; unreachable fails the run. ${VAR} is read
+# from the server's environment and a missing variable fails the run.
+#
+# semantic_engine:
+#   vendor: cube                    # cube | looker
+#   base_url: https://cube.example.com
+#   api_token: "${CUBE_API_TOKEN}"  # Looker: client_id + client_secret instead