open-data-sci 0.1.0__py3-none-any.whl

open_data_sci-0.1.0.dist-info/METADATA

@@ -0,0 +1,629 @@
+Metadata-Version: 2.4
+Name: open-data-sci
+Version: 0.1.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: Bug Tracker, https://github.com/f4roukb/open-data-sci/issues
+Author-email: Farouk Boukil <b4farouk@gmail.com>
+License:                               Apache License
+                                Version 2.0, January 2004
+                             http://www.apache.org/licenses/
+        
+        TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+        
+        1. Definitions.
+        
+           "License" shall mean the terms and conditions for use, reproduction,
+           and distribution as defined by Sections 1 through 9 of this document.
+        
+           "Licensor" shall mean the copyright owner or entity authorized by
+           the copyright owner that is granting the License.
+        
+           "Legal Entity" shall mean the union of the acting entity and all
+           other entities that control, are controlled by, or are under common
+           control with that entity. For the purposes of this definition,
+           "control" means (i) the power, direct or indirect, to cause the
+           direction or management of such entity, whether by contract or
+           otherwise, or (ii) ownership of fifty percent (50%) or more of the
+           outstanding shares, or (iii) beneficial ownership of such entity.
+        
+           "You" (or "Your") shall mean an individual or Legal Entity
+           exercising permissions granted by this License.
+        
+           "Source" form shall mean the preferred form for making modifications,
+           including but not limited to software source code, documentation
+           source, and configuration files.
+        
+           "Object" form shall mean any form resulting from mechanical
+           transformation or translation of a Source form, including but
+           not limited to compiled object code, generated documentation,
+           and conversions to other media types.
+        
+           "Work" shall mean the work of authorship, whether in Source or
+           Object form, made available under the License, as indicated by a
+           copyright notice that is included in or attached to the work
+           (an example is provided in the Appendix below).
+        
+           "Derivative Works" shall mean any work, whether in Source or Object
+           form, that is based on (or derived from) the Work and for which the
+           editorial revisions, annotations, elaborations, or other modifications
+           represent, as a whole, an original work of authorship. For the purposes
+           of this License, Derivative Works shall not include works that remain
+           separable from, or merely link (or bind by name) to the interfaces of,
+           the Work and Derivative Works thereof.
+        
+           "Contribution" shall mean any work of authorship, including
+           the original version of the Work and any modifications or additions
+           to that Work or Derivative Works thereof, that is intentionally
+           submitted to Licensor for inclusion in the Work by the copyright owner
+           or by an individual or Legal Entity authorized to submit on behalf of
+           the copyright owner. For the purposes of this definition, "submitted"
+           means any form of electronic, verbal, or written communication sent
+           to the Licensor or its representatives, including but not limited to
+           communication on electronic mailing lists, source code control systems,
+           and issue tracking systems that are managed by, or on behalf of, the
+           Licensor for the purpose of discussing and improving the Work, but
+           excluding communication that is conspicuously marked or otherwise
+           designated in writing by the copyright owner as "Not a Contribution."
+        
+           "Contributor" shall mean Licensor and any individual or Legal Entity
+           on behalf of whom a Contribution has been received by Licensor and
+           subsequently incorporated within the Work.
+        
+        2. Grant of Copyright License. Subject to the terms and conditions of
+           this License, each Contributor hereby grants to You a perpetual,
+           worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+           copyright license to reproduce, prepare Derivative Works of,
+           publicly display, publicly perform, sublicense, and distribute the
+           Work and such Derivative Works in Source or Object form.
+        
+        3. Grant of Patent License. Subject to the terms and conditions of
+           this License, each Contributor hereby grants to You a perpetual,
+           worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+           (except as stated in this section) patent license to make, have made,
+           use, offer to sell, sell, import, and otherwise transfer the Work,
+           where such license applies only to those patent claims licensable
+           by such Contributor that are necessarily infringed by their
+           Contribution(s) alone or by combination of their Contribution(s)
+           with the Work to which such Contribution(s) was submitted. If You
+           institute patent litigation against any entity (including a
+           cross-claim or counterclaim in a lawsuit) alleging that the Work
+           or a Contribution incorporated within the Work constitutes direct
+           or contributory patent infringement, then any patent licenses
+           granted to You under this License for that Work shall terminate
+           as of the date such litigation is filed.
+        
+        4. Redistribution. You may reproduce and distribute copies of the
+           Work or Derivative Works thereof in any medium, with or without
+           modifications, and in Source or Object form, provided that You
+           meet the following conditions:
+        
+           (a) You must give any other recipients of the Work or
+                 Derivative Works a copy of this License; and
+        
+           (b) You must cause any modified files to carry prominent notices
+                 stating that You changed the files; and
+        
+           (c) You must retain, in the Source form of any Derivative Works
+                 that You distribute, all copyright, patent, trademark, and
+                 attribution notices from the Source form of the Work,
+                 excluding those notices that do not pertain to any part of
+                 the Derivative Works; and
+        
+           (d) If the Work includes a "NOTICE" text file as part of its
+                 distribution, then any Derivative Works that You distribute must
+                 include a readable copy of the attribution notices contained
+                 within such NOTICE file, excluding those notices that do not
+                 pertain to any part of the Derivative Works, in at least one
+                 of the following places: within a NOTICE text file distributed
+                 as part of the Derivative Works; within the Source form or
+                 documentation, if provided along with the Derivative Works; or,
+                 within a display generated by the Derivative Works, if and
+                 wherever such third-party notices normally appear. The contents
+                 of the NOTICE file are for informational purposes only and
+                 do not modify the License. You may add Your own attribution
+                 notices within Derivative Works that You distribute, alongside
+                 or as an addendum to the NOTICE text from the Work, provided
+                 that such additional attribution notices cannot be construed
+                 as modifying the License.
+        
+           You may add Your own copyright statement to Your modifications and
+           may provide additional or different license terms and conditions
+           for use, reproduction, or distribution of Your modifications, or
+           for any such Derivative Works as a whole, provided Your use,
+           reproduction, and distribution of the Work otherwise complies with
+           the conditions stated in this License.
+        
+        5. Submission of Contributions. Unless You explicitly state otherwise,
+           any Contribution intentionally submitted for inclusion in the Work
+           by You to the Licensor shall be under the terms and conditions of
+           this License, without any additional terms or conditions.
+           Notwithstanding the above, nothing herein shall supersede or modify
+           the terms of any separate license agreement you may have executed
+           with Licensor regarding such Contributions.
+        
+        6. Trademarks. This License does not grant permission to use the trade
+           names, trademarks, service marks, or product names of the Licensor,
+           except as required for reasonable and customary use in describing the
+           origin of the Work and reproducing the content of the NOTICE file.
+        
+        7. Disclaimer of Warranty. Unless required by applicable law or
+           agreed to in writing, Licensor provides the Work (and each
+           Contributor provides its Contributions) on an "AS IS" BASIS,
+           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+           implied, including, without limitation, any warranties or conditions
+           of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+           PARTICULAR PURPOSE. You are solely responsible for determining the
+           appropriateness of using or redistributing the Work and assume any
+           risks associated with Your exercise of permissions under this License.
+        
+        8. Limitation of Liability. In no event and under no legal theory,
+           whether in tort (including negligence), contract, or otherwise,
+           unless required by applicable law (such as deliberate and grossly
+           negligent acts) or agreed to in writing, shall any Contributor be
+           liable to You for damages, including any direct, indirect, special,
+           incidental, or consequential damages of any character arising as a
+           result of this License or out of the use or inability to use the
+           Work (including but not limited to damages for loss of goodwill,
+           work stoppage, computer failure or malfunction, or any and all
+           other commercial damages or losses), even if such Contributor
+           has been advised of the possibility of such damages.
+        
+        9. Accepting Warranty or Additional Liability. While redistributing
+           the Work or Derivative Works thereof, You may choose to offer,
+           and charge a fee for, acceptance of support, warranty, indemnity,
+           or other liability obligations and/or rights consistent with this
+           License. However, in accepting such obligations, You may act only
+           on Your own behalf and on Your sole responsibility, not on behalf
+           of any other Contributor, and only if You agree to indemnify,
+           defend, and hold each Contributor harmless for any liability
+           incurred by, or claims asserted against, such Contributor by reason
+           of your accepting any such warranty or additional liability.
+        
+        END OF TERMS AND CONDITIONS
+        
+        APPENDIX: How to apply the Apache License to your work.
+        
+           To apply the Apache License to your work, attach the following
+           boilerplate notice, with the fields enclosed by brackets "[]"
+           replaced with your own identifying information. (Don't include
+           the brackets!)  The text should be enclosed in the appropriate
+           comment syntax for the file format. We also recommend that a
+           file or class name and description of purpose be included on the
+           same "printed page" as the copyright notice for easier
+           identification within third-party archives.
+        
+        Copyright [2026] Farouk Boukil
+         
+        Licensed under the Apache License, Version 2.0 (the "License");
+        you may not use this file except in compliance with the License.
+        You may obtain a copy of the License at
+        
+              http://www.apache.org/licenses/LICENSE-2.0
+        
+        Unless required by applicable law or agreed to in writing, software
+        distributed under the License is distributed on an "AS IS" BASIS,
+        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+        See the License for the specific language governing permissions and
+        limitations under the License.
+License-File: LICENSE
+Keywords: agent,ai,analytics,data-science,machine-learning
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <3.13,>=3.12
+Requires-Dist: catboost<2.0.0,>=1.2.0
+Requires-Dist: category-encoders<3.0.0,>=2.6.0
+Requires-Dist: connectorx<1.0.0,>=0.3.0
+Requires-Dist: duckduckgo-search<7.0.0,>=6.0.0
+Requires-Dist: httpx<1.0.0,>=0.27.0
+Requires-Dist: imbalanced-learn<1.0.0,>=0.12.0
+Requires-Dist: langchain-anthropic<1.0.0,>=0.2.0
+Requires-Dist: langchain-core<1.0.0,>=0.3.0
+Requires-Dist: langchain-openai<1.0.0,>=0.2.0
+Requires-Dist: langgraph<1.0.0,>=0.2.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: networkx<4.0.0,>=3.0.0
+Requires-Dist: numpy<2.0.0,>=1.26.0
+Requires-Dist: optuna<4.0.0,>=3.6.0
+Requires-Dist: pandas[excel,feather,parquet]<3.0.0,>=2.0.0
+Requires-Dist: plotly<6.0.0,>=5.15.0
+Requires-Dist: polars[calamine]<2.0.0,>=1.0.0
+Requires-Dist: prophet<2.0.0,>=1.1.0
+Requires-Dist: pydantic-settings<3.0.0,>=2.0.0
+Requires-Dist: pydantic<3.0.0,>=2.0.0
+Requires-Dist: pyod<3.0.0,>=2.0.0
+Requires-Dist: python-dotenv<2.0.0,>=1.0.0
+Requires-Dist: pyyaml<7.0,>=6.0
+Requires-Dist: rich<14.0.0,>=13.0.0
+Requires-Dist: sandbox-runtime<1.0.0,>=0.2.0
+Requires-Dist: scikit-learn<2.0.0,>=1.5.0
+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<0.48.0,>=0.47.0
+Requires-Dist: umap-learn<1.0.0,>=0.5.0
+Requires-Dist: xgboost<3.0.0,>=2.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<1.0.0,>=0.2.0; extra == 'aws'
+Provides-Extra: azure
+Requires-Dist: azure-identity<2.0.0,>=1.15.0; extra == 'azure'
+Provides-Extra: dev
+Requires-Dist: kaggle<2.0.0,>=1.6.0; extra == 'dev'
+Requires-Dist: mypy<2.0.0,>=1.13.0; extra == 'dev'
+Requires-Dist: pandas-stubs<3.0.0,>=2.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio<1.0.0,>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov<5.0.0,>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-xdist<4.0.0,>=3.0.0; extra == 'dev'
+Requires-Dist: pytest<8.0.0,>=7.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: 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]<1.0.0,>=0.26.0; extra == 'docs'
+Provides-Extra: gcp
+Requires-Dist: langchain-google-vertexai<3.0.0,>=2.0.0; extra == 'gcp'
+Provides-Extra: gemini
+Requires-Dist: langchain-google-genai<3.0.0,>=2.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<1.0.0,>=0.2.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.
+
+## Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [TUI Reference](#tui-reference)
+- [Slash Commands](#slash-commands)
+- [File Attachments](#file-attachments)
+- [Key Bindings](#key-bindings)
+- [Themes](#themes)
+- [Python SDK](#python-sdk)
+- [Models](#models)
+- [Configuration](#configuration)
+- [Environment Variables](#environment-variables)
+
+---
+
+## Installation
+
+```bash
+pip install open-data-sci
+```
+
+**Requirements:**
+- 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
+
+# Linux (Arch)
+sudo pacman -S --noconfirm bubblewrap socat ripgrep
+```
+
+If you've cloned the repository, `make install-system-dependencies` runs the right command for your platform automatically.
+
+### Provider extras
+
+Install optional extras to unlock additional LLM providers:
+
+```bash
+pip install "open-data-sci[aws]"       # AWS Bedrock
+pip install "open-data-sci[gemini]"    # Google Gemini (AI Studio)
+pip install "open-data-sci[gcp]"       # Google Vertex AI
+pip install "open-data-sci[azure]"     # Azure OpenAI
+pip install "open-data-sci[ollama]"    # Ollama (local models)
+```
+
+### Capability extras
+
+```bash
+pip install "open-data-sci[jax]"       # Deep learning — JAX, Flax, Optax
+```
+
+The `[jax]` extra is required to use the **Deep Learning** skill. Without it, the agent's sandboxed Python environment has no training framework available.
+
+Multiple extras can be combined:
+
+```bash
+pip install "open-data-sci[aws,gemini,jax]"
+```
+
+---
+
+## Quick Start
+
+### Basic setup
+
+Set your API key and point OpenDataSci at your data:
+
+```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:
+
+```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 llama3.2:3b   # local, no key needed
+```
+
+### 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.
+
+```yaml
+# datasci.yaml
+provider: anthropic
+model: claude-sonnet-4-6
+secondary_provider: openai
+secondary_model: gpt-4o-mini
+temperature: 0.1
+thinking_budget: 8000
+```
+
+```bash
+opendatasci data.csv --config datasci.yaml
+```
+
+Annotated config files for every supported provider are available in [`examples/configs/`](examples/configs/).
+
+### Python SDK
+
+```python
+from opendatasci import create_agent
+
+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."):
+        print(event)
+```
+
+### More examples
+
+The [`examples/`](examples/README.md) directory covers TUI walkthroughs, batch scripts, Jupyter notebooks, and annotated config files across every supported provider.
+
+---
+
+## TUI Reference
+
+```
+opendatasci PATH [OPTIONS]
+```
+
+### Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `PATH` | Data file or directory to load into the workspace |
+
+### 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 |
+| `--debug` | `false` | Enable debug output — writes a detailed `opendatasci_debug.log` |
+| `--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 |
+
+### Examples
+
+```bash
+# Minimal — analyse a single file with the default Anthropic provider
+opendatasci data.xlsx
+
+# Switch provider and primary model
+opendatasci data.csv --provider openai --model gpt-4o
+
+# 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.4-mini
+
+# See all available providers
+opendatasci --list-providers
+```
+
+---
+
+## Slash Commands
+
+Type `/` in the input box to trigger autocomplete. All commands are available at any time.
+
+| Command | Description |
+|---------|-------------|
+| `/clear` | Clear conversation context (preserves session variables and loaded data) |
+| `/compact` | Summarise and compress conversation history to free up context |
+| `/help` | Show all available commands |
+| `/ls-workspace` | List all files currently in the workspace |
+| `/models` | Show the primary and secondary model in use |
+| `/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 |
+
+---
+
+## File Attachments
+
+Attach files or code snippets to any message using the `@` prefix:
+
+```
+@path/to/file.py                      # attach an entire file
+@path/to/notebook.ipynb:L10-L40      # attach a specific line range
+```
+
+The agent sees the attached content as structured context inline with your message. Paths are resolved relative to your current working directory.
+
+---
+
+## 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 |
+
+---
+
+## Themes
+
+Select a theme at launch with `--theme`. Run `/themes` inside the TUI to see descriptions.
+
+| 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 |
+
+---
+
+## Python SDK
+
+The async-first Python API gives full programmatic control over the agent.
+
+### Basic usage
+
+```python
+from opendatasci import create_agent
+
+async with create_agent("sales.xlsx") as agent:
+    async for event in agent.astream("What is the average revenue by region?"):
+        print(event)
+```
+
+### Custom provider and model
+
+```python
+from opendatasci import OpenDataSciConfig, create_agent
+
+config = OpenDataSciConfig(
+    provider="openai",
+    model="gpt-4o",
+    openai_api_key="sk-...",
+    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."):
+        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`) |
+| `llm_server_base_url` | Custom API base URL — required for `ollama` and `openai_compatible_server` (env: `LLM_SERVER_BASE_URL`) |
+
+---
+
+## Models
+
+OpenDataSci supports every major LLM provider. Pass `--provider` to the TUI or set it in `OpenDataSciConfig`.
+
+| Provider | Flag | Extra required | Default model |
+|----------|------|----------------|---------------|
+| Anthropic | `anthropic` | *(none — default)* | `claude-sonnet-4-6` |
+| OpenAI | `openai` | *(none)* | `gpt-5.5` |
+| OpenAI-compatible server (e.g. vLLM) | `openai_compatible_server` | *(none)* | `meta-llama/Llama-3.2-3B-Instruct` |
+| AWS Bedrock | `bedrock` | `open-data-sci[aws]` | `us.anthropic.claude-sonnet-4-6` |
+| Google Gemini | `gemini` | `open-data-sci[gemini]` | `gemini-2.5-pro` |
+| Google Vertex AI | `vertexai` | `open-data-sci[gcp]` | `gemini-2.5-pro` |
+| Azure OpenAI | `azure` | `open-data-sci[azure]` | `gpt-4o` |
+| Ollama | `ollama` | `open-data-sci[ollama]` | `llama3.2:3b` |
+
+Pass `--list-providers` to print this table from the TUI at any time.
+
+---
+
+## Configuration
+
+### Workspace files
+
+Place these files inside your workspace's `.opendatasci/` directory:
+
+| Path | Purpose |
+|------|---------|
+| `.opendatasci/mcp.json` | MCP server URLs — connects the agent to external tool servers |
+| `.opendatasci/plans/` | Persisted plan files — auto-managed, one file per planning session |
+
+### Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `ANTHROPIC_API_KEY` | API key for the Anthropic provider |
+| `OPENAI_API_KEY` | API key for the OpenAI provider |
+| `REGION` | Cloud provider region |
+| `LLM_SERVER_BASE_URL` | Custom API base URL — used by `ollama` and `openai_compatible_server` providers |
+| `SKILLS_DIRECTORY` | Path to a directory of user-defined skill files (overrides none by default) |
+| `BUILTIN_SKILLS_DIRECTORY` | Path to the built-in skills directory (defaults to the bundled `resources/skills`) |
+| `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.