open-data-sci 0.2.1__tar.gz → 0.3.0__tar.gz

{open_data_sci-0.2.1 → open_data_sci-0.3.0}/.env.example

@@ -79,17 +79,14 @@ LLM_SERVER_BASE_URL=
 # OPENAI_API_KEY=
 
 # ── Sampling ───────────────────────────────────────────
-TEMPERATURE=
+PRIMARY_TEMPERATURE=
 
 # ── Agent customization ────────────────────────────────
 NAME=
 MCP_SERVERS=
 
-# ── Web access ─────────────────────────────────────────
-EXTRA_FETCH_DOMAINS=
-
 # ── Context management ─────────────────────────────────
-MIDTURN_COMPACTION_THRESHOLD=
+AUTOCOMPACTION_THRESHOLD=
 
 # ── Skills ─────────────────────────────────────────────
 # Path to a directory of user-defined skill files (.yaml, .yml, .json, .md).

{open_data_sci-0.2.1 → open_data_sci-0.3.0}/PKG-INFO

@@ -1,10 +1,10 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: open-data-sci
-Version: 0.2.1
+Version: 0.3.0
 Summary: AI agent for data science and machine learning
 Project-URL: Homepage, https://github.com/f4roukb/open-data-sci
 Project-URL: Repository, https://github.com/f4roukb/open-data-sci
-Project-URL: Documentation, https://open-data-sci.readthedocs.io
+Project-URL: Documentation, https://opendatasci.readthedocs.io/en/latest/
 Project-URL: Bug Tracker, https://github.com/f4roukb/open-data-sci/issues
 Author-email: Farouk Boukil <b4farouk@gmail.com>
 License:                               Apache License
@@ -220,6 +220,7 @@ Requires-Dist: catboost<2.0.0,>=1.2.0
 Requires-Dist: category-encoders<3.0.0,>=2.6.0
 Requires-Dist: duckdb<2.0.0,>=1.0.0
 Requires-Dist: duckduckgo-search<9.0.0,>=8.0.0
+Requires-Dist: httpx2<3.0.0,>=2.5.0
 Requires-Dist: httpx<1.0.0,>=0.27.0
 Requires-Dist: imbalanced-learn<1.0.0,>=0.12.0
 Requires-Dist: langchain-anthropic<2.0.0,>=1.0.0
@@ -229,10 +230,12 @@ Requires-Dist: langgraph<2.0.0,>=1.0.0
 Requires-Dist: lightgbm<5.0.0,>=4.0.0
 Requires-Dist: lxml<7.0.0,>=6.1.0
 Requires-Dist: matplotlib<4.0.0,>=3.7.0
+Requires-Dist: mcp<3.0.0,>=2.0.0
 Requires-Dist: networkx<4.0.0,>=3.0.0
 Requires-Dist: numpy<2.5.0,>=2.0.0
 Requires-Dist: optuna<5.0.0,>=4.0.0
 Requires-Dist: pandas[excel,feather,parquet]<4.0.0,>=3.0.0
+Requires-Dist: pillow<13.0.0,>=11.0.0
 Requires-Dist: plotly<7.0.0,>=6.0.0
 Requires-Dist: polars[calamine]<2.0.0,>=1.0.0
 Requires-Dist: prophet<2.0.0,>=1.1.0
@@ -248,15 +251,23 @@ Requires-Dist: scipy<2.0.0,>=1.14.0
 Requires-Dist: seaborn<1.0.0,>=0.12.0
 Requires-Dist: shap<1.0.0,>=0.46.0
 Requires-Dist: statsmodels<1.0.0,>=0.14.0
+Requires-Dist: textual-image<1.0.0,>=0.13.0
 Requires-Dist: textual<9.0.0,>=8.0.0
 Requires-Dist: umap-learn<1.0.0,>=0.5.0
 Requires-Dist: xgboost<4.0.0,>=3.0.0
 Requires-Dist: xxhash<4.0.0,>=3.5.0
 Provides-Extra: aws
 Requires-Dist: boto3<2.0.0,>=1.34.0; extra == 'aws'
-Requires-Dist: langchain-aws<2.0.0,>=1.0.0; extra == 'aws'
+Requires-Dist: langchain-aws<2.0.0,>=1.4.0; extra == 'aws'
 Provides-Extra: azure
 Requires-Dist: azure-identity<2.0.0,>=1.15.0; extra == 'azure'
+Provides-Extra: deep-learning
+Requires-Dist: flax<1.0.0,>=0.8.0; extra == 'deep-learning'
+Requires-Dist: jax<1.0.0,>=0.4.0; extra == 'deep-learning'
+Requires-Dist: optax<1.0.0,>=0.2.0; extra == 'deep-learning'
+Requires-Dist: sentence-transformers<4.0.0,>=3.0.0; extra == 'deep-learning'
+Requires-Dist: torch<3.0.0,>=2.0.0; extra == 'deep-learning'
+Requires-Dist: transformers<5.0.0,>=4.0.0; extra == 'deep-learning'
 Provides-Extra: dev
 Requires-Dist: kaggle<3.0.0,>=2.0.0; extra == 'dev'
 Requires-Dist: mypy<3.0.0,>=2.0.0; extra == 'dev'
@@ -268,39 +279,51 @@ Requires-Dist: pytest-xdist<4.0.0,>=3.0.0; extra == 'dev'
 Requires-Dist: pytest<10.0.0,>=9.0.0; extra == 'dev'
 Requires-Dist: ruff<1.0.0,>=0.8.0; extra == 'dev'
 Requires-Dist: types-openpyxl<4.0.0,>=3.1.0; extra == 'dev'
+Requires-Dist: types-pyyaml<7.0.0,>=6.0.0; extra == 'dev'
 Requires-Dist: vulture<3.0.0,>=2.0.0; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: mkdocs-material<10.0.0,>=9.5.0; extra == 'docs'
 Requires-Dist: mkdocs<2.0.0,>=1.6.0; extra == 'docs'
 Requires-Dist: mkdocstrings[python]<2.0.0,>=1.0.0; extra == 'docs'
+Provides-Extra: finance
+Requires-Dist: yfinance<1.0.0,>=0.2.0; extra == 'finance'
 Provides-Extra: gcp
 Requires-Dist: langchain-google-vertexai<4.0.0,>=3.0.0; extra == 'gcp'
 Provides-Extra: gemini
 Requires-Dist: langchain-google-genai<5.0.0,>=4.0.0; extra == 'gemini'
-Provides-Extra: jax
-Requires-Dist: flax<1.0.0,>=0.8.0; extra == 'jax'
-Requires-Dist: jax[cpu]<1.0.0,>=0.4.0; extra == 'jax'
-Requires-Dist: optax<1.0.0,>=0.2.0; extra == 'jax'
 Provides-Extra: ollama
 Requires-Dist: langchain-ollama<2.0.0,>=1.0.0; extra == 'ollama'
 Description-Content-Type: text/markdown
 
 # OpenDataSci
 
-A production-grade AI agent for data science and machine learning. See the [project README](../../README.md) for an overview, benchmark results, and feature descriptions.
+[![PyPI version](https://img.shields.io/pypi/v/open-data-sci.svg)](https://pypi.org/project/open-data-sci/)
+[![Python versions](https://img.shields.io/pypi/pyversions/open-data-sci.svg)](https://pypi.org/project/open-data-sci/)
+[![License](https://img.shields.io/pypi/l/open-data-sci.svg)](https://pypi.org/project/open-data-sci/)
+
+A production-grade AI agent for data science and machine learning — run it as an interactive terminal app, or embed it as an async Python SDK in your own service.
+
+- **Every major LLM provider** — Anthropic, OpenAI, AWS Bedrock, Google Gemini/Vertex AI, Azure OpenAI, Ollama, or any OpenAI-compatible server ([details](#models))
+- **Sandboxed code execution** — the agent writes and runs real Python and CLI code against your data, isolated from the host
+- **Zero-config first run** — point it at a file or directory and an interactive wizard handles the rest; every setting is also scriptable through YAML, environment variables, or the Python SDK
+- **Extensible** — connect [MCP servers](#mcp-servers) for extra tools, or add [custom skills](#custom-skills) to specialise the agent for a domain
+- **Cloud-portable architecture** — every stateful dependency (workspace, sandbox, memory, sessions, background tasks) sits behind an abstract interface, so a multi-tenant deployment is a matter of swapping implementations rather than rewriting the agent ([details](#cloud-portability))
+
+Full documentation, including the complete Python API reference: https://opendatasci.readthedocs.io/en/latest/
 
 ## Contents
 
 - [Installation](#installation)
 - [Quick Start](#quick-start)
+- [First Launch: The Setup Wizard](#first-launch-the-setup-wizard)
 - [TUI Reference](#tui-reference)
 - [Slash Commands](#slash-commands)
+- [The `/config` Panel](#the-config-panel)
 - [File Attachments](#file-attachments)
-- [Key Bindings](#key-bindings)
-- [Themes](#themes)
 - [Python SDK](#python-sdk)
+- [Cloud Portability](#cloud-portability)
 - [Models](#models)
-- [Configuration](#configuration)
+- [MCP Servers](#mcp-servers)
 - [Custom Skills](#custom-skills)
 - [Environment Variables](#environment-variables)
 
@@ -316,25 +339,11 @@ pip install open-data-sci
 - Python: 3.12
 - Platform: macOS or Linux (Windows is not supported)
 
-### System dependencies
-
-The sandbox that runs model-generated code shells out to native binaries that `pip` cannot install. Install them with your OS package manager before using the agent:
-
-```bash
-# macOS
-brew install ripgrep
-
-# Linux (Debian/Ubuntu)
-sudo apt-get install -y bubblewrap socat ripgrep
-
-# Linux (Fedora)
-sudo dnf install -y bubblewrap socat ripgrep
+**You don't need to configure anything before running the TUI.** `opendatasci` alone launches an interactive setup wizard the first time it runs — see [First Launch](#first-launch-the-setup-wizard). The steps below matter if you want everything ready ahead of time (scripted installs, containers, CI), or if you're embedding OpenDataSci as a library rather than running the TUI.
 
-# Linux (Arch)
-sudo pacman -S --noconfirm bubblewrap socat ripgrep
-```
+### System dependencies
 
-If you've cloned the repository, `make install-system-dependencies` runs the right command for your platform automatically.
+The sandbox that runs model-generated code shells out to native binaries that `pip` cannot install: `ripgrep` everywhere, plus `bubblewrap` and `socat` on Linux. **The TUI detects a missing dependency on first launch and offers to install it for you** — you only need to install them by hand if you're setting things up ahead of time (scripted installs, containers, CI) or skip that step in the wizard. See the documentation for the exact command per platform, including the optional GitHub CLI (`gh`) install needed for the built-in **`github.com`** skill.
 
 ### Provider extras
 
@@ -348,50 +357,53 @@ pip install "open-data-sci[azure]"     # Azure OpenAI
 pip install "open-data-sci[ollama]"    # Ollama (local models)
 ```
 
+Anthropic, OpenAI, and any OpenAI-compatible server (e.g. vLLM) work with no extra.
+
 ### Capability extras
 
 ```bash
-pip install "open-data-sci[jax]"       # Deep learning — JAX, Flax, Optax
+pip install "open-data-sci[deep-learning]" # Deep learning on the host — PyTorch, JAX, Transformers, Sentence-Transformers
+pip install "open-data-sci[finance]"       # Finance data — yfinance
 ```
 
-The `[jax]` extra is required to use the **Deep Learning** skill. Without it, the agent's sandboxed Python environment has no training framework available.
+The `[deep-learning]` extra — deep learning directly on the host, for machines with a GPU or NPU — is required to use the **Deep Learning** skill; without it, the agent's sandboxed Python environment has no training framework available. The `[finance]` extra is required to use the **`finance.yahoo.com`** skill.
+
+> **GPU access inside the sandbox is opt-in, and it's a real host-kernel exposure.** Installing a `[deep-learning]` package makes the sandbox bind-mount the host's accelerator device nodes so those frameworks can actually use the hardware — a materially different risk than the sandbox's filesystem/network isolation, since it hands sandboxed code direct access to the host kernel's GPU driver. A warning is logged whenever this activates; uninstall the `[deep-learning]` packages to disable it entirely. See the documentation for the full breakdown (device nodes, per-platform coverage, and the underlying risk).
 
 Multiple extras can be combined:
 
 ```bash
-pip install "open-data-sci[aws,gemini,jax]"
+pip install "open-data-sci[aws,gemini,deep-learning,finance]"
 ```
 
 ---
 
 ## Quick Start
 
-### Basic setup
-
-Set your API key and point OpenDataSci at your data:
+Point OpenDataSci at your data — nothing else required:
 
 ```bash
-export ANTHROPIC_API_KEY=sk-ant-...
 opendatasci data.csv
 ```
 
-A `.env` file in the working directory is loaded automatically, so you can also place it there:
+On a first run, a wizard walks you through picking a provider/model and entering whatever secret it needs (e.g. an API key) — see [First Launch](#first-launch-the-setup-wizard). Everything you enter is remembered for next time, so this only happens once per machine, not once per project.
+
+If you already have an API key set (as an environment variable or in a `.env` file in the working directory), the wizard skips straight past that field:
 
 ```bash
 # .env
 ANTHROPIC_API_KEY=sk-ant-...
 ```
 
-To use a different provider, pass `--provider`:
-
 ```bash
-opendatasci data.csv --provider openai --api-key sk-...
-opendatasci data.csv --provider ollama --model qwen3.5:9b   # local, no key needed
+opendatasci data.csv
 ```
 
+Everything — provider, model, secondary model, theme — can also be changed after launch without restarting, from the `/config` panel (alias `/settings`; see [Slash Commands](#slash-commands)).
+
 ### Setup with a config file
 
-For a reusable configuration across projects, create a YAML file and pass it with `--config`. TUI flags always take precedence over values in the file.
+For a reusable configuration across projects, create a YAML file and pass it with `--config`. Whatever the file sets is used as-is; anything it leaves out (including provider/model selection, which then falls back to the wizard) is still picked up interactively.
 
 ```yaml
 # datasci.yaml
@@ -399,28 +411,49 @@ provider: anthropic
 model: claude-sonnet-5
 secondary_provider: openai
 secondary_model: gpt-5.6-luna
-temperature: 0.1
+primary_temperature: 0.1
 ```
 
 ```bash
 opendatasci data.csv --config datasci.yaml
 ```
 
-Annotated config files for every supported provider are available in [`examples/configs/`](examples/configs/).
+An annotated config file ships for every supported provider.
 
-### Python SDK
+### Quick start with the Python SDK
 
 ```python
-from opendatasci import create_agent
+from opendatasci import create_agent, Invocation
 
 async with create_agent("data.csv") as agent:
-    async for event in agent.astream("Summarise this dataset and train a model on the target column."):
+    invocation = Invocation.from_text("Summarise this dataset and train a model on the target column.")
+    async for event in agent.astream(invocation):
         print(event)
 ```
 
-### More examples
+There's no wizard here — the SDK is not the TUI, so provide `config=OpenDataSciConfig(...)` (or set env vars) up front. See [Python SDK](#python-sdk) below for more, including custom providers.
 
-The [`examples/`](examples/README.md) directory covers TUI walkthroughs, batch scripts, Jupyter notebooks, and annotated config files across every supported provider.
+---
+
+## First Launch: The Setup Wizard
+
+The very first time you run `opendatasci` (or any time it detects nothing was resolved from `--config`/env), it runs you through up to three steps before handing control to the chat. Every step is skipped automatically once it's already satisfied, so a second launch on the same machine is typically instant.
+
+### 1. System dependencies check
+
+If a required sandbox binary (`ripgrep`, and on Linux `bubblewrap`/`socat`) isn't installed, a one-time screen explains what's missing and offers to install it for you with your OS package manager (you may be prompted for your password). Decline, and it shows the exact command to run yourself, then lets you continue anyway — the sandbox is only needed once the agent actually executes code, so this step never blocks you from reaching the chat.
+
+**Setting this up manually ahead of time (see [System dependencies](#system-dependencies)) makes the wizard skip this step entirely** — useful for scripted installs, Docker images, or CI, where there's no one at the keyboard to answer the prompt.
+
+### 2. Provider & model selection
+
+A short, linear flow (theme, then whichever of primary/secondary provider and model aren't already set) — one choice per screen, arrow keys to pick, no back button. Set any of these non-interactively with `--config` (see [Setup with a config file](#setup-with-a-config-file)); the wizard only asks about whatever the file leaves unresolved.
+
+### 3. Provider secrets
+
+Whatever the chosen provider still needs — an API key, an Azure endpoint, a GCP project ID — is collected one field at a time. Each value is saved as you enter it (to `~/.opendatasci/secrets/api.yaml`), so quitting partway through doesn't lose what you've already typed, and it won't be asked again on a later launch. Environment variables and `.env` always take precedence over this saved file, so a value you export or add to `.env` later overrides whatever the wizard remembered.
+
+Everything the wizard sets can be changed afterwards, live, from the `/config` panel — see [The `/config` panel](#the-config-panel).
 
 ---
 
@@ -434,42 +467,28 @@ opendatasci PATH [OPTIONS]
 
 | Argument | Description |
 |----------|-------------|
-| `PATH` | Data file or directory to load into the workspace |
+| `PATH` | Data file or directory to load into the workspace. Defaults to the current directory when omitted |
 
 ### Options
 
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--provider` | `anthropic` | LLM provider for the primary model. Choices: `anthropic`, `openai`, `bedrock`, `gemini`, `vertexai`, `azure`, `ollama`, `openai_compatible_server` |
-| `--model` | *(provider default)* | Primary model name — provider-specific identifier. Omit to use the provider's default (see [Models](#models)) |
-| `--secondary-provider` | *(same as `--provider`)* | Provider for the secondary (auxiliary) model — may differ from `--provider` |
-| `--secondary-model` | *(provider default)* | Secondary model name for lightweight tasks (summarisation, etc.) |
-| `--api-key` | *(env var)* | API key for the primary provider. Falls back to the standard env var for the selected provider |
-| `--theme` | `default` | Colour palette. Choices: `default`, `accessible`, `light`, `solarized`, `dracula`. Run `/themes` inside the TUI for descriptions |
-| `--config` | *(none)* | Path to a YAML file containing `OpenDataSciConfig` fields; explicit TUI flags take precedence |
-| `--list-providers` | | Print all supported providers and their default models, then exit |
-| `--version` | | Print the installed version, then exit |
+| Flag | Description |
+|------|-------------|
+| `--config FILE` | Path to a YAML file containing `OpenDataSciConfig` fields. Fields it sets are used as-is; anything it doesn't set (including theme, which it never sets) is picked interactively on startup |
+| `--version` | Print the installed version, then exit |
+
+Provider, model, secondary provider/model, theme, and API keys are set through `--config`, environment variables/`.env`, or the interactive wizard/`/config` panel. If you're scripting a launch and want it to never prompt, use `--config` (and make sure any secrets it needs are in the environment).
 
 ### Examples
 
 ```bash
-# Minimal — analyse a single file with the default Anthropic provider
+# Minimal — analyse a single file, wizard fills in whatever's missing
 opendatasci data.xlsx
 
-# Switch provider and primary model
-opendatasci data.csv --provider openai --model gpt-5.6-sol
-
-# Bedrock with a region
-REGION=us-west-2 opendatasci ./project/ --provider bedrock
-
-# Colour-blind safe theme
-opendatasci data.parquet --theme accessible
-
-# Mix providers — heavy model on one, lightweight secondary on another
-opendatasci data.csv --provider anthropic --secondary-provider openai --secondary-model gpt-5.6-luna
+# Fully non-interactive, everything resolved from the file + env
+opendatasci data.csv --config datasci.yaml
 
-# See all available providers
-opendatasci --list-providers
+# Bedrock, credentials from the environment, model/provider from the file
+REGION=us-west-2 opendatasci ./project/ --config examples/configs/config_bedrock.yaml
 ```
 
 ---
@@ -482,129 +501,98 @@ Type `/` in the input box to trigger autocomplete. All commands are available at
 |---------|-------------|
 | `/cancel-all-messages` | Cancel all messages queued while the agent was busy |
 | `/cancel-message` | Cancel the most recently queued message |
-| `/clear` | Clear conversation context (preserves session variables and loaded data) |
+| `/clear` | Clear conversation context (workspace files are untouched) |
 | `/compact` | Summarise and compress conversation history to free up context |
+| `/config` (alias `/settings`) | Open the [configuration panel](#the-config-panel) — theme, models, providers, MCP servers, and more |
 | `/help` | Show all available commands |
 | `/ls-workspace` | List all files currently in the workspace |
-| `/models` | Show the primary and secondary model in use |
+| `/models` | Jump straight into `/config`'s Models section (primary/secondary provider and model, primary temperature) |
 | `/reset` | Reset the agent session and reload data from disk |
-| `/stop` | Stop the currently running agent turn (future messages resume from where it left off) |
-| `/themes` | List available colour themes with descriptions |
 | `/exit` | Quit OpenDataSci |
 
+Switching provider or model from `/config` rebuilds the agent in the background; if the new provider/model fails to start (e.g. a missing API key), the error is reported and your current session keeps running untouched.
+
 Sending a message while the agent is still working doesn't reject it — it's pinned above the input box as a queued message and run automatically, in order, once the agent finishes (unless the agent is waiting on your answer to a question). Use `/cancel-message` or `/cancel-all-messages` to discard queued messages instead of waiting for them to run.
 
+When the agent schedules work in the background (e.g. concurrent worker agents running an ensemble sweep), a **Background** line in the header shows which tasks are still running. You don't need to check back manually — as soon as a background task finishes, the agent picks it up and continues on its own.
+
 ---
 
-## File Attachments
+## The `/config` Panel
 
-Attach files or code snippets to any message using the `@` prefix:
+Run `/config` (or `/settings` — same command, either name works) to open a navigable menu covering every setting the agent needs, organised into sections:
 
-```
-@path/to/file.py                      # attach an entire file
-@path/to/notebook.ipynb:L10-L40      # attach a specific line range
-```
+| Section | What's in it |
+|---------|--------------|
+| **Display** | Theme; Tips (toggle the rotating footer hints) |
+| **Integrations** | **MCP Servers** — add, verify, or remove [MCP servers](#mcp-servers) the agent can call, either by loading candidates from an `mcp.json` file or entering one manually (name, URL, transport, headers); **Custom skills** — point at a folder of [custom skills](#custom-skills) |
+| **Models** | Grouped under **Primary Model** (provider, model, sampling temperature) and **Secondary Model** (provider, model) — picking a new provider resets its paired model to that provider's default, and the model choices offered depend on whichever provider is currently selected |
+| **Personalization** | Agent display name |
+| **Subagents** | Worker timeout (max seconds a spawned worker may run) |
 
-The agent sees the attached content as structured context inline with your message. Paths are resolved relative to your current working directory.
+Navigate with arrow keys and Enter, back out a level with Escape. Changing a model or provider applies immediately in the background — a failed switch (bad key, unreachable server) leaves your current session running untouched and reports the error instead.
 
 ---
 
-## Key Bindings
-
-| Key | Action |
-|-----|--------|
-| `Ctrl+C` (×2) | Quit |
-| `Ctrl+D` | Quit |
-| `Ctrl+R` | Reset session |
-| `Ctrl+L` | Clear conversation |
-| `Escape` | Focus input box |
-| `Tab` / `Shift+Tab` | Cycle through autocomplete suggestions |
-| `↑` / `↓` | Navigate input history or autocomplete |
-
----
+## File Attachments
 
-## Themes
+Attach files or code snippets to any message using the `@` prefix:
 
-Select a theme at launch with `--theme`. Run `/themes` inside the TUI to see descriptions.
+```
+@path/to/file.py                      # attach an entire file
+```
 
-| Name | Description |
-|------|-------------|
-| `default` | Dark background with muted accents (built-in default) |
-| `accessible` | Okabe-Ito palette — colour-blind safe |
-| `light` | Light background with dark text |
-| `solarized` | Solarized Dark by Ethan Schoonover |
-| `dracula` | Dracula — vivid pastels on near-black |
+While typing, matching files are discovered relative to your current working directory. The message sent to the agent carries a reference to the resolved absolute path rather than the file's content — the agent reads the file itself using its own file-reading tool.
 
 ---
 
 ## Python SDK
 
-The async-first Python API gives full programmatic control over the agent.
+The async-first Python API gives full programmatic control over the agent, independent of the TUI — this is what you reach for to embed OpenDataSci in a script, a service, a desktop app, or a notebook.
 
 ### Basic usage
 
 ```python
-from opendatasci import create_agent
+from opendatasci import Invocation, create_agent
 
 async with create_agent("sales.xlsx") as agent:
-    async for event in agent.astream("What is the average revenue by region?"):
+    async for event in agent.astream(Invocation.from_text("What is the average revenue by region?")):
         print(event)
 ```
 
 ### Custom provider and model
 
 ```python
-from opendatasci import OpenDataSciConfig, create_agent
+from opendatasci import Invocation, OpenDataSciConfig, create_agent
 
 config = OpenDataSciConfig(
     provider="openai",
     model="gpt-5.6-sol",
     openai_api_key="sk-...",
-    temperature=0.2,
+    primary_temperature=0.2,
 )
 
 async with create_agent("data.parquet", config=config) as agent:
-    async for event in agent.astream("Train a gradient boosting model on the target column."):
+    async for event in agent.astream(Invocation.from_text("Train a gradient boosting model on the target column.")):
         print(event)
 ```
 
-### `OpenDataSciConfig` reference
-
-| Field | Description |
-|-------|-------------|
-| `provider` | LLM provider (`"anthropic"`, `"openai"`, `"bedrock"`, `"gemini"`, `"vertexai"`, `"azure"`, `"ollama"`, `"openai_compatible_server"`) |
-| `model` | Primary model identifier — omit to use the provider default |
-| `secondary_provider` | Provider for the lightweight secondary model — defaults to the primary provider |
-| `secondary_model` | Secondary model identifier — omit to use the provider default |
-| `anthropic_api_key` | Anthropic API key (env: `ANTHROPIC_API_KEY`) |
-| `openai_api_key` | OpenAI / OpenAI-compatible server API key (env: `OPENAI_API_KEY`) |
-| `google_api_key` | Google Gemini API key (env: `GOOGLE_API_KEY`) |
-| `azure_api_key` | Azure OpenAI API key (env: `AZURE_OPENAI_API_KEY`) |
-| `aws_region` | AWS region for Bedrock (env: `REGION`) |
-| `google_cloud_project` | GCP project ID for Vertex AI (env: `GOOGLE_CLOUD_PROJECT`) |
-| `google_cloud_location` | Vertex AI region (env: `GOOGLE_CLOUD_LOCATION`) |
-| `azure_endpoint` | Azure OpenAI resource endpoint URL (env: `AZURE_OPENAI_ENDPOINT`) |
-| `azure_api_version` | Azure OpenAI API version — defaults to `2025-01-01-preview` (env: `AZURE_OPENAI_API_VERSION`) |
-| `llm_server_base_url` | Custom API base URL — required for `ollama` and `openai_compatible_server` (env: `LLM_SERVER_BASE_URL`) |
-| `temperature` | Sampling temperature — not sent to Claude 4.6+ / Sonnet 5 models, which use adaptive thinking (env: `TEMPERATURE`) |
-| `name` | Display name for the agent — defaults to `"Sai"` (env: `NAME`) |
-| `mcp_servers` | List of MCP server URLs the agent may connect to (env: `MCP_SERVERS`) |
-| `extra_web_domains` | Additional hostnames the `fetch_url` tool may retrieve, on top of the built-in allowlist (env: `EXTRA_FETCH_DOMAINS`) |
-| `override_web_domains` | When set, replaces the built-in domain allowlist entirely — `extra_web_domains` is still applied on top |
-| `skills_directory` | Path to a directory of custom skill files loaded in addition to built-ins (env: `SKILLS_DIRECTORY`) |
-| `builtin_skills_directory` | Path to the built-in skills directory — override only to replace defaults entirely (env: `BUILTIN_SKILLS_DIRECTORY`) |
-| `worker_timeout_seconds` | Max seconds to wait for spawned workers to finish — `null` disables the timeout, default `300` (env: `WORKER_TIMEOUT_SECONDS`) |
-| `midturn_compaction_threshold` | Token count at which context is compacted mid-turn — default `96000` (env: `MIDTURN_COMPACTION_THRESHOLD`) |
-| `local_code_exec_timeout` | Max seconds for a single sandboxed code-execution run — default `1800` (env: `CODE_EXEC_TIMEOUT`) |
+There's no wizard here — `OpenDataSciConfig` is a plain `pydantic-settings` model that never prompts for anything, so code built on the SDK directly is responsible for supplying whatever the chosen provider needs, same as any other library. See the documentation for the complete field-by-field reference (every field, its environment variable alias, and its default), plus patterns for headless batch processing, long-lived sessions, and multi-tenant deployment.
+
+---
+
+## Cloud Portability
+
+Every stateful dependency OpenDataSci relies on — where it stores data, where it runs code, where it keeps memory — sits behind an abstract interface (workspace, sandbox, project memory, session mapping, conversation checkpoints, background tasks, skill registry, human approval), and the local backend shipped today is just one implementation of each. None of this is enabled out of the box — the shipped implementations are all local. Swap in a cloud-infrastructure-backed implementation of the same interface (e.g. an S3-compatible object store for the workspace, Firecracker microVMs for sandboxing, Valkey for session state) and the agent keeps working unchanged, which is what makes moving OpenDataSci into a multi-tenant or distributed deployment a matter of configuration and infrastructure choice, not a rewrite. See the documentation for the full list of interfaces and their recommended cloud implementations.
 
 ---
 
 ## Models
 
-OpenDataSci supports every major LLM provider. Pass `--provider` to the TUI or set it in `OpenDataSciConfig`.
+OpenDataSci supports every major LLM provider. Pass `provider`/`model` in your `--config` YAML or `OpenDataSciConfig`, or pick them from the setup wizard / `/config` → Models.
 
-| Provider | Flag | Extra required | Default model |
-|----------|------|----------------|---------------|
+| Provider | Value | Extra required | Default model |
+|----------|-------|-----------------|---------------|
 | Anthropic | `anthropic` | *(none — default)* | `claude-sonnet-5` |
 | OpenAI | `openai` | *(none)* | `gpt-5.6-sol` |
 | OpenAI-compatible server (e.g. vLLM) | `openai_compatible_server` | *(none)* | `Qwen/Qwen3.5-4B` |
@@ -614,37 +602,39 @@ OpenDataSci supports every major LLM provider. Pass `--provider` to the TUI or s
 | Azure OpenAI | `azure` | `open-data-sci[azure]` | `gpt-5.6-sol` |
 | Ollama | `ollama` | `open-data-sci[ollama]` | `qwen3.5:9b` |
 
-Pass `--list-providers` to print this table from the TUI at any time.
-
 ---
 
-## Configuration
+## MCP Servers
 
-### Workspace files
+Connect the agent to external [Model Context Protocol](https://modelcontextprotocol.io) servers to give it additional tools. Only the two remote transports are supported — `http` (Streamable HTTP) and `sse` (Server-Sent Events) — a server reachable only via stdio (`command`/`args`) is out of scope, since OpenDataSci never launches a child process to talk to one.
 
-Place these files inside your workspace's `.opendatasci/` directory:
+### From the TUI
 
-| Path | Purpose |
-|------|---------|
-| `.opendatasci/mcp.json` | MCP server definitions — connects the agent to external tool servers |
-| `.opendatasci/plans/` | Persisted plan files — auto-managed, one file per planning session |
+The easiest path: `/config` → Integrations → MCP Servers. Load candidate servers from an existing `mcp.json` file (pick which to add — these are added as-is, with no connectivity check), or add one manually (name, URL, transport, headers) — a manually-added server is tested and must connect successfully before it's kept.
 
-`mcp.json` uses the same convention as Cursor:
+Tools are (re)discovered from every configured server at the start of each turn, not just once at startup, so enabling/disabling tools on the server side takes effect without restarting OpenDataSci.
+
+### Via the SDK
+
+```python
+from opendatasci import OpenDataSciConfig, create_agent
+from opendatasci.tools.mcp import MCPServerSpec, MCPTransport
 
-```json
-{
-  "mcpServers": {
-    "my-server":   { "url": "http://localhost:8080" },
-    "another":     { "url": "http://localhost:9000" }
-  }
-}
+config = OpenDataSciConfig(
+    mcp_servers=[
+        MCPServerSpec(name="my-server", url="http://localhost:8080", transport=MCPTransport.HTTP),
+    ]
+)
+
+async with create_agent("data.csv", config=config) as agent:
+    ...
 ```
 
 ---
 
 ## Custom Skills
 
-Skills are Markdown (or YAML/JSON) files that give the agent a specialised persona and instruction set. OpenDataSci ships several built-in skills; you can add your own at the workspace level or point the agent at any directory you choose.
+Skills are Markdown files that give the agent a specialised persona and instruction set. OpenDataSci ships several built-in skills; you can add your own at the workspace level or point the agent at any directory you choose.
 
 ### Workspace skills (recommended)
 
@@ -675,13 +665,13 @@ You are a time-series forecasting specialist. When analysing data, always...
 
 ### Global skills directory
 
-To share skills across workspaces, set `SKILLS_DIRECTORY` in your environment or `.env` file:
+To share skills across workspaces, set `SKILLS_DIRECTORY` in your environment or `.env` file — or point `/config` → Integrations → Custom skills at it live from inside the TUI:
 
 ```bash
 SKILLS_DIRECTORY=/home/user/my-skills
 ```
 
-This directory is scanned *in addition to* the workspace `.opendatasci/skills/` directory and the built-in skills. When two sources define a skill with the same name, the later source wins (built-ins → workspace → `SKILLS_DIRECTORY`).
+This directory is scanned *in addition to* the workspace `.opendatasci/skills/` directory and the built-in skills. When two sources define a skill with the same name, the later source wins (built-ins → workspace → `SKILLS_DIRECTORY`). Skill *domains* have the equivalent `SKILL_DOMAINS_DIRECTORY`.
 
 You can also pass `skills_directory` directly when using the Python SDK:
 
@@ -694,10 +684,19 @@ async with create_agent("data.csv", config=config) as agent:
     ...
 ```
 
-### Environment variables
+---
+
+## Environment Variables
+
+Each variable below is also settable as a field on `OpenDataSciConfig` directly in the Python SDK — use whichever fits your setup.
 
 | Variable | Description |
 |----------|-------------|
+| `PROVIDER` | LLM provider for the primary model (default: `anthropic`) |
+| `MODEL` | Primary model identifier (default: provider default) |
+| `SECONDARY_PROVIDER` | Provider for the secondary model (default: `anthropic`, independent of `PROVIDER`) |
+| `SECONDARY_MODEL` | Secondary model for lightweight tasks (default: provider default) |
+| `NAME` | Agent display name, injected into all system prompts (default: `Sai`) |
 | `ANTHROPIC_API_KEY` | API key for the Anthropic provider |
 | `OPENAI_API_KEY` | API key for the OpenAI / OpenAI-compatible server provider |
 | `GOOGLE_API_KEY` | API key for the Google Gemini provider |
@@ -708,12 +707,14 @@ async with create_agent("data.csv", config=config) as agent:
 | `AZURE_OPENAI_ENDPOINT` | Azure OpenAI resource endpoint URL |
 | `AZURE_OPENAI_API_VERSION` | Azure OpenAI API version (default: `2025-01-01-preview`) |
 | `LLM_SERVER_BASE_URL` | Custom API base URL — used by `ollama` and `openai_compatible_server` providers |
-| `TEMPERATURE` | LLM sampling temperature |
-| `MCP_SERVERS` | Comma-separated list of MCP server URLs |
+| `PRIMARY_TEMPERATURE` | LLM sampling temperature for the primary model |
+| `MCP_SERVERS` | MCP server definitions — see [MCP Servers](#mcp-servers) |
 | `SKILLS_DIRECTORY` | Path to a directory of user-defined skill files |
 | `BUILTIN_SKILLS_DIRECTORY` | Path to the built-in skills directory (defaults to the bundled skills) |
+| `SKILL_DOMAINS_DIRECTORY` | Path to a directory of user-defined skill domains |
+| `BUILTIN_SKILL_DOMAINS_DIRECTORY` | Path to the built-in skill domains directory (defaults to the bundled domains) |
 | `WORKER_TIMEOUT_SECONDS` | Max seconds to wait for spawned workers (default: `300`) |
-| `MIDTURN_COMPACTION_THRESHOLD` | Token count at which context is compacted mid-turn (default: `96000`) |
+| `AUTOCOMPACTION_THRESHOLD` | Token count at which context is compacted mid-turn (default: `96000`) |
 | `CODE_EXEC_TIMEOUT` | Max seconds for a single sandboxed code execution (default: `1800`) |
 
-A `.env` file in the working directory is loaded automatically at startup.
+A `.env` file in the working directory is loaded automatically at startup. A `--config` YAML file's fields take precedence over environment variables and `.env`, which in turn take precedence over whatever the setup wizard has saved to `~/.opendatasci/settings/global.yaml` and `~/.opendatasci/secrets/api.yaml`.