@oxy-hq/cli 0.1.0

package/json-schemas/agentic.json

@@ -0,0 +1,406 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "AgentConfig",
+  "description": "Top-level agent configuration.",
+  "type": "object",
+  "properties": {
+    "context": {
+      "description": "Glob patterns for context files (`.view.yml`, `.topic.yml`, `.sql`, `.md`).  Resolved relative to the directory containing the YAML file.",
+      "default": [],
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "databases": {
+      "description": "Database names from config.yml to use as connectors.\n\nEach string is the `name:` of a database entry in the project's `config.yml`.  The HTTP layer resolves these names to live connectors (via [`BuildContext`]) so that connection details are defined once and reused across agents.  All database types supported by Oxy (DuckDB, Postgres, BigQuery, Snowflake, ClickHouse, …) can be listed here.\n\n```yaml databases: - local - analytics_db ```",
+      "default": [],
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "instructions": {
+      "description": "Global instructions injected into every LLM call.",
+      "default": null,
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "llm": {
+      "$ref": "#/definitions/LlmConfigYaml"
+    },
+    "semantic_engine": {
+      "description": "Optional vendor semantic engine configuration.\n\nWhen absent, the solver routes exclusively through the internal semantic model and LLM paths (identical to today's behaviour).",
+      "anyOf": [
+        {
+          "$ref": "#/definitions/SemanticEngineConfig"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "states": {
+      "description": "Per-state overrides.",
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/StateConfig"
+      }
+    },
+    "thinking": {
+      "description": "Global thinking/reasoning config applied to all pipeline states.\n\nCan be overridden per-state via the `states:` section.\n\n```yaml thinking: adaptive        # shorthand # — or — thinking: effort: medium          # low | medium | high | xhigh | max ```\n\n`{ budget_tokens: N }` is also accepted, but only Claude 4.6 and earlier take it — 4.7+ rejects that form, and `effort` is the graded control there. Prefer `effort` unless you need a hard ceiling on an older model.",
+      "anyOf": [
+        {
+          "$ref": "#/definitions/ThinkingConfigYaml"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "timezone": {
+      "description": "IANA timezone (e.g. `America/Los_Angeles`) used to resolve the Today-is date hint and relative dates like `yesterday` or `last week`. Defaults to UTC when unset.",
+      "default": null,
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "validation": {
+      "description": "Validation rule configuration.\n\nWhen absent, all built-in rules run with their default parameters. Use this section to disable specific rules or tune parameters such as the outlier detection threshold:\n\n```yaml validation: rules: solved: - name: outlier_detection enabled: true threshold_sigma: 3.0 min_rows: 6 ```",
+      "default": null,
+      "anyOf": [
+        {
+          "$ref": "#/definitions/ValidationConfig"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "definitions": {
+    "ExtendedThinkingConfigYaml": {
+      "description": "Extended thinking mode preset configuration.\n\nOverrides the default model and/or thinking config when the user activates \"extended thinking\" mode from the UI.",
+      "type": "object",
+      "properties": {
+        "model": {
+          "description": "Model ID override for extended thinking mode.",
+          "default": null,
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "thinking": {
+          "description": "Thinking config override for extended thinking mode.",
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ThinkingConfigYaml"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
+    "LlmConfigYaml": {
+      "type": "object",
+      "properties": {
+        "api_key": {
+          "description": "API key.  Falls back to `ANTHROPIC_API_KEY` (Anthropic) or `OPENAI_API_KEY` (OpenAi / OpenAiCompat) environment variables.",
+          "default": null,
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "base_url": {
+          "description": "Base URL override.\n\n- Anthropic: proxy URL (default: `https://api.anthropic.com/v1/messages`) - OpenAi: Responses API base (default: `https://api.openai.com/v1/responses`) - OpenAiCompat: local server root, e.g. `http://localhost:11434/v1`",
+          "default": null,
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "extended_thinking": {
+          "description": "\"Extended thinking\" mode preset: an alternative model + thinking configuration activated at runtime via the UI toggle.\n\n```yaml llm: thinking: effort:low extended_thinking: model: gpt-5.4 thinking: effort:medium ```",
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ExtendedThinkingConfigYaml"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "max_tokens": {
+          "description": "Maximum output tokens per call.  Defaults to 4096.",
+          "default": null,
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint32",
+          "minimum": 0.0
+        },
+        "model": {
+          "description": "Model ID.  Overrides the `model_ref` resolved from `ref`.",
+          "default": null,
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "ref": {
+          "description": "Named model reference from the project's `config.yml`.\n\nWhen set, the vendor, api_key, and base_url of that model entry are used as defaults and any other fields in this section override them.\n\n```yaml llm: ref: openai-4o-mini   # model name from config.yml model: gpt-5.4        # override the model_ref only ```",
+          "default": null,
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "thinking": {
+          "description": "Default thinking/reasoning config for all pipeline states.\n\nTakes precedence over the top-level `thinking:` field on `AgentConfig`.\n\n```yaml llm: thinking: adaptive ```",
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ThinkingConfigYaml"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "vendor": {
+          "description": "Backend vendor.  Defaults to [`LlmVendor::Anthropic`] when neither this field nor `ref` supplies one.\n\nOverrides the vendor resolved from `ref` when both are set — which is what lets a `config.yml` model supply the managed `key_var` secret and `api_url` while the agent redirects the call to a different wire protocol:\n\n```yaml llm: ref: o4-mini            # inherits key_var secret + api_url vendor: open_ai_compat  # …but talk /chat/completions, not /responses ```\n\n`Option` rather than a defaulted `LlmVendor` on purpose: the override above is only expressible if \"user wrote `anthropic`\" is distinguishable from \"field absent\". While this was a bare `LlmVendor` it silently defaulted, so the ref's vendor always won and this field did nothing whenever `ref` was set.",
+          "anyOf": [
+            {
+              "$ref": "#/definitions/LlmVendor"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
+    "LlmVendor": {
+      "description": "LLM vendor / backend selector.\n\n```yaml llm: vendor: open_ai_compat   # Ollama, vLLM, LM Studio, LangDock, … model: llama3.2 base_url: http://localhost:11434/v1 ```\n\n`rename_all = \"snake_case\"` derives `open_ai` / `open_ai_compat` from the variant names. The elided spellings (`openai`, `openai_compat`) are the ones people actually reach for — and were what this doc comment advertised while serde rejected them — so both are accepted as aliases.",
+      "oneOf": [
+        {
+          "description": "Anthropic Messages API (default).  Uses `ANTHROPIC_API_KEY`.",
+          "type": "string",
+          "enum": [
+            "anthropic"
+          ]
+        },
+        {
+          "description": "OpenAI Responses API (`/v1/responses`).  Uses `OPENAI_API_KEY`.\n\nNote this is the **Responses** API, not Chat Completions — third-party OpenAI-compatible gateways that only implement `/chat/completions` (LangDock, many EU/self-hosted proxies) will 404 here. Use [`LlmVendor::OpenAiCompat`] for those.",
+          "type": "string",
+          "enum": [
+            "open_ai"
+          ]
+        },
+        {
+          "description": "OpenAI-compatible Chat Completions API (`/v1/chat/completions`). Suitable for Ollama, vLLM, LM Studio, LangDock, and similar self-hosted or third-party gateways.  Uses `OPENAI_API_KEY` as fallback (or pass `api_key` directly).",
+          "type": "string",
+          "enum": [
+            "open_ai_compat"
+          ]
+        }
+      ]
+    },
+    "RuleEntry": {
+      "description": "One entry in a rule list.\n\nExtra TOML/YAML keys beyond `name` and `enabled` are collected into `params` via `#[serde(flatten)]`.  Each rule's constructor deserialises `params` into its own typed struct using [`serde_json::from_value`].\n\n# Example YAML ```yaml - name: outlier_detection enabled: true threshold_sigma: 3.0 min_rows: 6 ```",
+      "type": "object",
+      "required": [
+        "name"
+      ],
+      "properties": {
+        "enabled": {
+          "default": true,
+          "type": "boolean"
+        },
+        "name": {
+          "type": "string"
+        }
+      }
+    },
+    "RuleSetConfig": {
+      "description": "Rules grouped by pipeline stage.",
+      "type": "object",
+      "properties": {
+        "solvable": {
+          "description": "Rules applied after the **Solve** stage.",
+          "default": [],
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/RuleEntry"
+          }
+        },
+        "solved": {
+          "description": "Rules applied after the **Execute** stage.",
+          "default": [],
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/RuleEntry"
+          }
+        },
+        "specified": {
+          "description": "Rules applied after the **Specify** stage.",
+          "default": [],
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/RuleEntry"
+          }
+        }
+      }
+    },
+    "SemanticEngineConfig": {
+      "description": "Configuration for an external vendor semantic engine.\n\n```yaml semantic_engine: vendor: cube base_url: https://cube.example.com api_token: \"${CUBE_API_TOKEN}\"\n\n# — OR for Looker — semantic_engine: vendor: looker base_url: https://myco.looker.com client_id: \"${LOOKER_CLIENT_ID}\" client_secret: \"${LOOKER_CLIENT_SECRET}\" ```",
+      "type": "object",
+      "required": [
+        "base_url",
+        "vendor"
+      ],
+      "properties": {
+        "api_token": {
+          "description": "API token (Cube).  Supports `\"${ENV_VAR}\"` interpolation.",
+          "default": null,
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "base_url": {
+          "type": "string"
+        },
+        "client_id": {
+          "description": "OAuth client ID (Looker).",
+          "default": null,
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "client_secret": {
+          "description": "OAuth client secret (Looker).",
+          "default": null,
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "vendor": {
+          "$ref": "#/definitions/VendorKind"
+        }
+      }
+    },
+    "StateConfig": {
+      "type": "object",
+      "properties": {
+        "instructions": {
+          "description": "Additional instructions injected for this state only.",
+          "default": null,
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "max_retries": {
+          "description": "Maximum tool-use rounds before failing.",
+          "default": null,
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint32",
+          "minimum": 0.0
+        },
+        "model": {
+          "description": "Model ID override for this state.\n\nWhen set, this model is used instead of the global `llm.model`. The vendor, API key, and base URL from the global `llm:` section are inherited; only the model ID is replaced.\n\n```yaml states: clarifying: model: claude-haiku-4-5   # cheap model for fast triage solving: model: claude-opus-4-6    # powerful model for SQL generation ```",
+          "default": null,
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "thinking": {
+          "description": "Thinking/reasoning config for this state.",
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ThinkingConfigYaml"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
+    "ThinkingConfigYaml": {
+      "description": "Thinking configuration as expressed in YAML.\n\nAccepts a shorthand string (`\"adaptive\"`, `\"disabled\"`, `\"effort:<level>\"`) or a map with either `budget_tokens` or `effort`.\n\nWhich forms a model accepts is not a preference. On Claude 4.7 and later, `budget_tokens` is rejected by the API and `effort` is the only graded control over thinking depth; on 4.6 and earlier, `budget_tokens` works and is the only way to set a hard ceiling. The provider translates a `budget_tokens` config on a model that refuses it rather than failing the request, and warns.\n\nBecause this enum is `#[serde(untagged)]`, schemars emits a JSON Schema `oneOf` with each variant represented by its structural shape (a plain string for [`ThinkingConfigYaml::Shorthand`] and an object for [`ThinkingConfigYaml::Manual`] / [`ThinkingConfigYaml::Effort`]). Serde discriminates at runtime by trying variants in declaration order, so there is no parse ambiguity. Some IDEs, however, validate each `oneOf` branch independently and may annotate a valid string with \"invalid against variant 2 / variant 3\" warnings — those are cosmetic and the file still deserializes correctly at runtime.",
+      "anyOf": [
+        {
+          "description": "Shorthand string: `\"adaptive\"`, `\"disabled\"`, or `\"effort:<level>\"` for any level below.",
+          "type": "string"
+        },
+        {
+          "description": "Explicit budget: `budget_tokens: N`.\n\nClaude 4.6 and earlier only. Claude 4.7+ removed this form; the Anthropic provider translates it to an effort level there rather than letting the request 400, and warns. Prefer `effort:` on those models.",
+          "type": "object",
+          "required": [
+            "budget_tokens"
+          ],
+          "properties": {
+            "budget_tokens": {
+              "type": "integer",
+              "format": "uint32",
+              "minimum": 0.0
+            }
+          }
+        },
+        {
+          "description": "Reasoning effort: `effort: low|medium|high|xhigh|max`.\n\nOn Claude this is `output_config.effort` alongside adaptive thinking -- the only graded control over thinking depth on 4.7+. On OpenAI the top two levels clamp to `high`.",
+          "type": "object",
+          "required": [
+            "effort"
+          ],
+          "properties": {
+            "effort": {
+              "type": "string"
+            }
+          }
+        }
+      ]
+    },
+    "ValidationConfig": {
+      "description": "Validation section of the agent YAML config.",
+      "type": "object",
+      "properties": {
+        "rules": {
+          "default": {
+            "specified": [],
+            "solvable": [],
+            "solved": []
+          },
+          "allOf": [
+            {
+              "$ref": "#/definitions/RuleSetConfig"
+            }
+          ]
+        }
+      }
+    },
+    "VendorKind": {
+      "description": "Vendor identifier for bundled semantic engine adapters.\n\nInternal to the config layer — never part of the `SemanticEngine` public API.",
+      "type": "string",
+      "enum": [
+        "cube",
+        "looker"
+      ]
+    }
+  }
+}