docs/capabilities.md

# Headless capability matrix

Quick reference for what Headless inspects, what Cobuild builds, and what can be
re-run. For the operating workflow, start with
[`skills/dataiku-headless/SKILL.md`](../skills/dataiku-headless/SKILL.md) and load
its object-specific references as directed.

## The rule

**Flow and analytic logic is always built by Cobuild.** Headless has no tool to create
or change recipe logic, code, inputs, or outputs, or to create or modify the definition
of an ML analysis, dashboard, insight, agent, agent tool, scenario, webapp, wiki article,
data quality rule, knowledge bank, semantic model, or evaluation store. The container
execution override below changes only which container an existing object runs in.

Headless writes Dataiku objects directly in four cases: **bootstrap** (get a project
or local content onto the instance so Cobuild has something to work with), **project
configuration**, **cross-project**, and **instance-level administration**. It also
re-runs assets that already exist. Some bootstrap writes do land inside a project —
see the table below.
Local profile actions are listed separately because they only change which Dataiku
instance the local client targets.


## Instance types

The configured instance type controls which tools can run in both stdio and HTTP.
The catalog stays the same; each tool advertises its allowed types in metadata,
and dispatch rejects unsupported calls before authentication delegation or execution.
Dataiku permissions and API availability still apply to permitted calls.

| Instance type | Available tools |
|---|---|
| design | All existing explicit tools |
| automation | Reads, existing asset execution, instance administration, and project-folder operations; no Cobuild or project definition/content writes |
| agent-management, govern, deployer | Instance controls only; API tools for these node types are not implemented yet |

Automation excludes all six Cobuild tools, even conversation listing and polling,
and `create_project`, `update_project_settings`, `set_project_variables`,
`set_container_exec_config`, `create_upload_dataset`, `create_managed_folder`,
`upload_file_to_managed_folder`, `write_project_library_file`.
It permits `build_datasets`, `run_recipe`, `run_scenario`, `abort_job`, metric
recomputation through `get_dataset_metrics`, and every
project-folder operation, including creation, deletion, and moving projects.
Existing execution can modify outputs; this policy does not make Automation read-only.

Instance controls are `list_instances`, `switch_instance`, `configure_instance`,
`delete_instance`, and `get_current_instance`. The first four also work without an
active selection, subject to the existing HTTP restrictions on local configuration.
For Design and Automation, a failed `get_current_instance` connection check returns
`connection_status=failed` and the exception text in the error field.
For Agent Management, Govern and Deployer, `get_current_instance` returns sanitized profile metadata
with connection_status set to unsupported, without contacting DSS or reporting a version.
Agent Management, Govern and Deployer profiles can be saved without a connection
test. Design and Automation require a successful DSS connection test in local setup.

## Surface

**131 tools** · 93 read · 24 direct Dataiku write · 6 Cobuild · 4 execute · 3 local
profile · 1 connection test

| Bucket | # | Scope |
|---|---|---|
| Read / inspect | 93 | Never mutates |
| Direct Dataiku write | 24 | Bootstrap, project configuration, cross-project, admin |
| Cobuild conversation | 6 | All flow and analytic building |
| Execute | 5 | `build_datasets`, `run_recipe`, `run_scenario`, `abort_job`, `get_dataset_metrics` (recomputes metrics before reading them) |
| Local profile action | 3 | `configure_instance`, `switch_instance`, `delete_instance` |
| Connection test | 1 | `test_connection` |

Buckets count each tool once by what it does. The tables below group by area instead, so a
tool can appear in the **Local instance targeting** section while counting in a different
bucket here.

## Built by Cobuild — limited direct exceptions

Three partial exceptions: Headless can create a dataset from a local file, create an
empty managed folder, and select container execution for an existing object (see
*Handled directly by Headless*). It cannot build or change analytic logic here.

| Area | Inspect | Direct action |
|---|---|---|
| Datasets | `list_datasets`, `get_dataset_info`, `get_dataset_sample`, `get_dataset_profile`, `get_dataset_metrics`, `get_dataset_column_descriptions`, `export_dataset` | `build_datasets` |
| Recipes | `list_recipes`, `get_recipe_settings` | `set_container_exec_config`, `run_recipe` |
| Flow & zones | `get_flow_graph`, `list_flow_zones`, `get_flow_object_metadata` | — |
| ML analyses | `list_ml_analyses`, `get_ml_analysis_summary`, `get_ml_analysis_settings`, `list_ml_analysis_models`, `get_ml_model_details` | `set_container_exec_config` (single-ML-task analyses) |
| Saved models | `list_saved_models`, `list_saved_model_versions`, `get_saved_model_version_details` | — |
| Agents | `list_agents`, `get_agent_settings`, `list_agent_versions`, `list_agent_tools`, `get_agent_tool_settings` | `set_container_exec_config` (agent tools) |
| Agent reviews | `list_agent_reviews`, `get_agent_review`, `list_agent_review_tests`, `list_agent_review_runs`, `get_agent_review_run_results` | — |
| Scenarios | `list_scenarios`, `get_scenario_settings`, `get_scenario_run_history`, `list_messaging_channels` | `run_scenario` |
| Dashboards & insights | `list_dashboards`, `get_dashboard_settings`, `list_insights`, `get_insight_settings` | — |
| Webapps | `list_webapps`, `get_webapp_settings`, `get_webapp_state` | `set_container_exec_config` |
| Wikis | `list_wiki_articles`, `get_wiki_article` | — |
| Data quality | `list_data_quality_rules`, `get_data_quality_status`, `get_data_quality_rule`, `get_data_quality_rule_results`, `get_data_quality_rule_history` | — |
| LLMs & knowledge banks | `list_llms`, `get_llm_info`, `list_knowledge_banks`, `get_knowledge_bank_settings`, `search_knowledge_bank`, `list_rag_llms`, `get_rag_llm_settings` | `set_container_exec_config` (knowledge banks) |
| Semantic models | `list_semantic_models`, `get_semantic_model_version_config` | — |
| Evaluation stores | `list_evaluation_stores`, `get_evaluation_store_details` | — |

## Driving Cobuild

| Tool | Use |
|---|---|
| `start_cobuild_conversation` | Open a retained conversation on a project |
| `send_cobuild_message` | Ask Cobuild to inspect a project, or to build or change something — edits are opt-in via allow_edit_project |
| `answer_cobuild_question` | Answer a question Cobuild asked, resuming its pending work |
| `answer_cobuild_confirmation` | Approve or cancel a deletion Cobuild proposed; `APPROVE` deletes the listed objects |
| `get_cobuild_turn_status` | Poll a turn; recovers after a timeout or cancellation |
| `list_cobuild_conversations` | Find existing conversations for this instance and project |

## Handled directly by Headless

No Cobuild involved. Scope says what kind of access, and where a write lands.

| Area | Inspect | Act | Scope |
|---|---|---|---|
| Projects | `count_projects`, `list_projects`, `get_project_metadata`, `get_project_variables`, `get_project_settings` | `create_project`, `set_project_variables`, `update_project_settings` | Bootstrap and project configuration — direct writes are **in-project** |
| Container execution placement | `get_recipe_settings`, `get_ml_analysis_settings`, `get_webapp_settings`, `get_knowledge_bank_settings`, `get_agent_tool_settings`, `list_container_exec_configs` | `set_container_exec_config` | Project configuration, **in-project** — sets which container a recipe, ML task, WebApp backend, Knowledge Bank, or agent tool runs in. Saved-model retrains use their training recipe's `params.containerSelection`. |
| Uploaded Files datasets | — | `create_upload_dataset` | Bootstrap, **in-project** — supplied rows in HTTP; local files in stdio only |
| Managed folders | `list_managed_folders`, `get_managed_folder_info`, `get_managed_folder_contents` | `create_managed_folder`, `upload_file_to_managed_folder` | Bootstrap, **in-project** — local-file upload is stdio only |
| Project libraries | `list_project_library`, `read_project_library_file`, `search_project_library`, `validate_project_library_file` | `write_project_library_file` | Bootstrap, **in-project** — local-file write is stdio only |
| Project folders | `list_project_folders`, `get_project_folder` | `create_project_folder`, `move_project_to_folder`, `delete_project_folder` | Cross-project |
| Code environments | `list_code_envs` | `create_code_env`, `update_code_env`, `delete_code_env` | Instance-level |
| Plugins | `list_plugins`, `list_plugin_usages` | `install_plugin`, `ensure_plugin_code_env`, `update_plugin`, `delete_plugin` | Instance-level — local-path install/update are stdio only |
| Users | `list_users` | `create_user`, `update_user`, `delete_user` | Instance-level |
| Groups | `list_groups` | `create_group`, `update_group`, `delete_group` | Instance-level |
| Jobs | `list_jobs`, `get_job_status`, `get_job_log`, `get_future_status`, `wait_for_job` | `build_datasets`, `run_recipe`, `run_scenario`, `abort_job` | Execution — re-runs or stops assets that already exist |
| Connections | `list_connections`, `get_connection_info`, `test_connection` | — | Read-only |
| Instance settings | `list_container_exec_configs`, `list_spark_configs`, `get_licensing_status` | — | Read-only |
| Data collections & sharing | `list_data_collections`, `list_data_collection_objects`, `list_shared_objects` | — | Read-only |

The **in-project** writes above configure or supply a project; they do not build its
analytic logic. None of them build recipe logic, a model, or an agent.

The [plugin development guide](../skills/dataiku-headless/references/plugin-development.md)
explains how to write, test, and package plugins locally with the agent's file and
command tools. Headless can upload a package over stdio or install and update from Git over
either transport. It cannot create a
development plugin or edit its files on the instance.

## Local instance targeting

Local client configuration, not Dataiku objects.

| Tool | Effect |
|---|---|
| `configure_instance` | Connect a local stdio instance; opens a local page for URL, instance type, and API key (disabled in HTTP mode) |
| `switch_instance` | Change the active instance; in HTTP mode saves only the authenticated user’s selected catalog instance |
| `list_instances`, `get_current_instance` | Show configured instances, their declared types, and the active one; `get_current_instance` includes the Dataiku version when available |
| `delete_instance` | Removes a **saved instance profile from the local config file**. Does not touch the Dataiku instance. |