data-harness 0.1.3__tar.gz

data_harness-0.1.3/.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv python install ${{ matrix.python }}
+      - run: uv sync --python ${{ matrix.python }}
+      - run: uv run --python ${{ matrix.python }} ruff check data_harness tests
+      - run: uv run --python ${{ matrix.python }} ruff format --check data_harness tests
+      - run: uv run --python ${{ matrix.python }} pytest tests/ -m "not live"

data_harness-0.1.3/.github/workflows/release-testpypi.yml

@@ -0,0 +1,15 @@
+name: Release to TestPyPI
+
+on:
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv build
+      - run: uv publish --publish-url https://test.pypi.org/legacy/
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.TEST_PYPI_TOKEN }}

data_harness-0.1.3/.github/workflows/release.yml

@@ -0,0 +1,26 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv python install 3.12
+      - run: uv sync --python 3.12 --frozen
+      - run: uv run --python 3.12 ruff check data_harness tests
+      - run: uv run --python 3.12 ruff format --check data_harness tests
+      - run: uv run --python 3.12 pytest tests/ -m "not live"
+      - run: uv build --no-sources
+      - run: uv publish

data_harness-0.1.3/.gitignore

@@ -0,0 +1,25 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+env/
+.env
+*.egg
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+runs/
+*.jsonl
+.DS_Store
+plan/
+.claude/
+AGENTS.md
+CLAUDE.md
+blogs/
+.playwright-mcp/
+artifact-*.html
+smoke_results/

data_harness-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Max Khor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data_harness-0.1.3/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: data-harness
+Version: 0.1.3
+Summary: Data agent with Python-native tools (no bash)
+Project-URL: Homepage, https://github.com/maxkskhor/data-harness
+Project-URL: Repository, https://github.com/maxkskhor/data-harness
+Project-URL: Issues, https://github.com/maxkskhor/data-harness/issues
+Author: Max Khor
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: anthropic
+Requires-Dist: loguru
+Requires-Dist: numpy
+Requires-Dist: pandas
+Provides-Extra: dev
+Requires-Dist: openai; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest-mock; extra == 'dev'
+Requires-Dist: python-dotenv; extra == 'dev'
+Provides-Extra: openai
+Requires-Dist: openai; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# data-harness
+
+*(data + ReAct — a controlled data-agent SDK for Python workflows)*
+
+A data-native agent SDK for Python — built around controlled execution, handle-based state, provider adapters, sessions, subagents, and reconstructable runs.
+
+Most agent frameworks hand the model a shell and call it a day. `data-harness` takes a different approach: the model operates through a constrained Python interpreter, with data stored in a session cache and exposed as named handles. No bash. Explicit state. Logs that can reconstruct what happened.
+
+`data-harness` began as an installable reference implementation for harness design. It is now developing into the full SDK/framework track. A separate `learn-data-harness` repository will be created after the SDK stabilises to extract the basic principles without async, production sandboxing, or SDK-heavy features.
+
+The design is covered in a three-part series:
+
+- [Designing a ReAct Harness for Data Workflows Without Bash](https://maxkskhor.substack.com/p/designing-a-react-harness-for-data)
+- [How a Bash-Free Data Agent Remembers Its Work](https://maxkskhor.substack.com/p/how-a-bash-free-data-agent-remembers)
+- [The Bugs Hidden Inside a Data Agent Harness](https://maxkskhor.substack.com/p/the-engineering-invariants-behind)
+
+---
+
+## Why no bash?
+
+Giving an agent shell access is the path of least resistance, but it creates real problems in production: unpredictable side effects, security exposure, and behaviour that's hard to reproduce. `data-harness` deliberately constrains the model to Python only — which turns out to be enough for most data workloads and forces cleaner tool design.
+
+---
+
+## Core design decisions
+
+Each decision here is intentional. Understanding them is the point.
+
+**Handle/snapshot pattern**
+Large objects (DataFrames, arrays, query results) live in a `SessionCache`, not in message history. The model only sees a compact snapshot — shape, columns, a few sample rows. It accesses the data by writing Python against the handle name. This keeps context lean without hiding data from the model.
+
+**Prefix-stable system prompt**
+The system prompt never changes between turns. Reminders, state, and nags are appended to the conversation suffix. This is a KV-cache discipline: a stable prefix means the provider can cache it, which reduces latency and cost on long runs.
+
+**Progressive connector disclosure**
+Data connectors (databases, APIs, warehouses) are registered but hidden from the tool list until explicitly loaded. A shorter tool list means the model makes better routing decisions. Connectors are only visible when relevant.
+
+**Subagent isolation**
+Spawned subagents get a fresh adapter and a fresh cache. State is transferred explicitly via `input_handles`. No implicit shared state. This makes subagent behaviour reproducible and debuggable.
+
+**Suffix-only nag reminders**
+The planner escalates reminders at 4 / 8 / 12 turns without progress. These are always appended to the suffix, never inserted into the prefix, so the KV cache is never busted by reminder text.
+
+**JSONL turn logging**
+Every turn is logged to a `.jsonl` file from the start. Not bolted on later. Each line is a complete turn record including latency, token counts, and cache hit/miss. Reproducibility is a first-class concern.
+
+---
+
+## Install
+
+```bash
+# requires Python 3.10+ and uv
+uv sync
+```
+
+## Quick start
+
+`Agent` needs a provider adapter. The adapter is the boundary between the
+provider SDK and the harness: it turns Anthropic/OpenAI responses into
+`data-harness`'s normalised `Message`, `ToolUseBlock`, and token-count types. It is
+explicit on purpose so the harness is not tied to one model provider, and tests
+can swap in `FakeAdapter` without touching the loop.
+
+For Anthropic:
+
+```python
+from data_harness import Agent
+from data_harness.providers.anthropic import AnthropicAdapter
+
+adapter = AnthropicAdapter(model="claude-sonnet-4-6")
+agent = Agent(adapter=adapter, system="You are a data analyst.")
+
+result = agent.run("Compute the mean of [1, 2, 3, 4, 5] and print it.")
+print(result)
+```
+
+For OpenAI, install the optional extra and change only the adapter:
+
+```bash
+pip install "data-harness[openai]"
+```
+
+```python
+from data_harness.providers.openai import OpenAIAdapter
+
+adapter = OpenAIAdapter(model="gpt-4o-mini")
+```
+
+Run the minimal Anthropic example:
+
+```bash
+uv run python examples/quickstart.py
+```
+
+`examples/quickstart.py` requires `ANTHROPIC_API_KEY` when run as a script. Tests import `build_agent()` and drive it with `FakeAdapter`, so the example stays covered without token spend.
+
+## Chat sessions
+
+`Agent.run()` is still the simple one-shot path: it starts a fresh message
+history each time. For chatbot or workbench applications, create a session and
+ask follow-up questions on it:
+
+```python
+from data_harness import Agent
+from data_harness.providers.openai import OpenAIAdapter
+
+adapter = OpenAIAdapter(model="gpt-4o-mini")
+agent = Agent(adapter=adapter, system="You are a data analyst.")
+
+session = agent.session()
+session.put("uploaded_data", df)
+
+print(session.ask("What columns are in the uploaded data?"))
+print(session.ask("Which numeric column has the highest average?"))
+```
+
+The session keeps one `Harness`, one message history, and one `SessionCache`.
+This is the path to use when a UI needs uploaded artefacts and conversation
+follow-up to stay in scope.
+
+## Connector example
+
+Connector helpers keep the quick path small while preserving progressive disclosure. Connector tools start hidden; the model must call `load_connectors` before it can use them.
+
+```python
+from data_harness import Agent
+from data_harness.providers.anthropic import AnthropicAdapter
+
+adapter = AnthropicAdapter(model="claude-sonnet-4-6")
+agent = Agent(adapter=adapter, system="You are a data analyst.")
+
+market_data = agent.connector(
+    "market_data",
+    description="Market data tools.",
+)
+
+
+def fetch_ohlcv(symbol: str) -> list[dict]:
+    return [{"symbol": symbol, "close": 101.2}]
+
+
+market_data.tool(
+    fetch_ohlcv,
+    description="Fetch OHLCV data for a ticker.",
+)
+
+result = agent.run("Load market_data and inspect AAPL.")
+print(result)
+```
+
+## What `Agent` composes
+
+`Agent` is a thin composition layer over the lower-level primitives:
+
+- A provider adapter translates model-provider SDK objects into the harness's normalised response types.
+- `Harness` owns the ReAct loop, messages, dispatch, reminders, and JSONL logging.
+- `SessionCache` stores large values as handles plus compact snapshots.
+- `AgentSession` keeps a chat-style harness and cache alive across follow-up questions.
+- `python_interpreter` is the controlled execution surface; there is no bash tool.
+- `list_variables` exposes cache handles without dumping raw payloads.
+- `ConnectorRegistry` keeps connector tools hidden until loaded.
+- `Planner` reminders and subagents are opt-in helpers, not a second runtime.
+
+For explicit wiring, read [examples/advanced_wiring.py](examples/advanced_wiring.py). The future `learn-data-harness` repository will provide the smaller, linear teaching guide once this SDK surface has stabilised.
+
+Run the advanced example - it loads a checked-in FRED unemployment-rate sample, runs analysis, uses subagents and the planner (requires `ANTHROPIC_API_KEY`):
+
+```bash
+uv run python examples/advanced_wiring.py
+```
+
+Run tests:
+
+```bash
+uv run pytest tests/ -v
+uv run pytest tests/smoke_tests.py -m live -v  # requires OPENAI_API_KEY
+```
+
+---
+
+## Project structure
+
+```
+data_harness/
+  loop.py          # Harness: the core ReAct loop
+  cache.py         # SessionCache: handle/snapshot storage
+  providers/       # Normalised adapter interface (Anthropic and OpenAI)
+  tools/
+    interpreter.py # Sandboxed Python executor
+    connectors.py  # Progressive connector registry
+    planner.py     # Plan/nag tool
+    subagent.py    # Isolated subagent spawning
+    variables.py   # list_variables tool
+  types.py         # Shared types: Message, ToolSpec, ContentBlock
+  logger.py        # JSONL turn logging
+  observe.py       # Latency measurement
+examples/
+  quickstart.py        # Minimal Agent path
+  advanced_wiring.py   # Explicit Harness wiring
+  data/                # Small public sample data for the advanced demo
+```
+
+---
+
+## Sandbox disclaimer
+
+The Python interpreter uses AST checks and restricted globals to reduce accidental misuse. It is not a container sandbox and should not be treated as safe for untrusted input.
+
+---
+
+## License
+
+MIT

data_harness-0.1.3/README.md

@@ -0,0 +1,213 @@
+# data-harness
+
+*(data + ReAct — a controlled data-agent SDK for Python workflows)*
+
+A data-native agent SDK for Python — built around controlled execution, handle-based state, provider adapters, sessions, subagents, and reconstructable runs.
+
+Most agent frameworks hand the model a shell and call it a day. `data-harness` takes a different approach: the model operates through a constrained Python interpreter, with data stored in a session cache and exposed as named handles. No bash. Explicit state. Logs that can reconstruct what happened.
+
+`data-harness` began as an installable reference implementation for harness design. It is now developing into the full SDK/framework track. A separate `learn-data-harness` repository will be created after the SDK stabilises to extract the basic principles without async, production sandboxing, or SDK-heavy features.
+
+The design is covered in a three-part series:
+
+- [Designing a ReAct Harness for Data Workflows Without Bash](https://maxkskhor.substack.com/p/designing-a-react-harness-for-data)
+- [How a Bash-Free Data Agent Remembers Its Work](https://maxkskhor.substack.com/p/how-a-bash-free-data-agent-remembers)
+- [The Bugs Hidden Inside a Data Agent Harness](https://maxkskhor.substack.com/p/the-engineering-invariants-behind)
+
+---
+
+## Why no bash?
+
+Giving an agent shell access is the path of least resistance, but it creates real problems in production: unpredictable side effects, security exposure, and behaviour that's hard to reproduce. `data-harness` deliberately constrains the model to Python only — which turns out to be enough for most data workloads and forces cleaner tool design.
+
+---
+
+## Core design decisions
+
+Each decision here is intentional. Understanding them is the point.
+
+**Handle/snapshot pattern**
+Large objects (DataFrames, arrays, query results) live in a `SessionCache`, not in message history. The model only sees a compact snapshot — shape, columns, a few sample rows. It accesses the data by writing Python against the handle name. This keeps context lean without hiding data from the model.
+
+**Prefix-stable system prompt**
+The system prompt never changes between turns. Reminders, state, and nags are appended to the conversation suffix. This is a KV-cache discipline: a stable prefix means the provider can cache it, which reduces latency and cost on long runs.
+
+**Progressive connector disclosure**
+Data connectors (databases, APIs, warehouses) are registered but hidden from the tool list until explicitly loaded. A shorter tool list means the model makes better routing decisions. Connectors are only visible when relevant.
+
+**Subagent isolation**
+Spawned subagents get a fresh adapter and a fresh cache. State is transferred explicitly via `input_handles`. No implicit shared state. This makes subagent behaviour reproducible and debuggable.
+
+**Suffix-only nag reminders**
+The planner escalates reminders at 4 / 8 / 12 turns without progress. These are always appended to the suffix, never inserted into the prefix, so the KV cache is never busted by reminder text.
+
+**JSONL turn logging**
+Every turn is logged to a `.jsonl` file from the start. Not bolted on later. Each line is a complete turn record including latency, token counts, and cache hit/miss. Reproducibility is a first-class concern.
+
+---
+
+## Install
+
+```bash
+# requires Python 3.10+ and uv
+uv sync
+```
+
+## Quick start
+
+`Agent` needs a provider adapter. The adapter is the boundary between the
+provider SDK and the harness: it turns Anthropic/OpenAI responses into
+`data-harness`'s normalised `Message`, `ToolUseBlock`, and token-count types. It is
+explicit on purpose so the harness is not tied to one model provider, and tests
+can swap in `FakeAdapter` without touching the loop.
+
+For Anthropic:
+
+```python
+from data_harness import Agent
+from data_harness.providers.anthropic import AnthropicAdapter
+
+adapter = AnthropicAdapter(model="claude-sonnet-4-6")
+agent = Agent(adapter=adapter, system="You are a data analyst.")
+
+result = agent.run("Compute the mean of [1, 2, 3, 4, 5] and print it.")
+print(result)
+```
+
+For OpenAI, install the optional extra and change only the adapter:
+
+```bash
+pip install "data-harness[openai]"
+```
+
+```python
+from data_harness.providers.openai import OpenAIAdapter
+
+adapter = OpenAIAdapter(model="gpt-4o-mini")
+```
+
+Run the minimal Anthropic example:
+
+```bash
+uv run python examples/quickstart.py
+```
+
+`examples/quickstart.py` requires `ANTHROPIC_API_KEY` when run as a script. Tests import `build_agent()` and drive it with `FakeAdapter`, so the example stays covered without token spend.
+
+## Chat sessions
+
+`Agent.run()` is still the simple one-shot path: it starts a fresh message
+history each time. For chatbot or workbench applications, create a session and
+ask follow-up questions on it:
+
+```python
+from data_harness import Agent
+from data_harness.providers.openai import OpenAIAdapter
+
+adapter = OpenAIAdapter(model="gpt-4o-mini")
+agent = Agent(adapter=adapter, system="You are a data analyst.")
+
+session = agent.session()
+session.put("uploaded_data", df)
+
+print(session.ask("What columns are in the uploaded data?"))
+print(session.ask("Which numeric column has the highest average?"))
+```
+
+The session keeps one `Harness`, one message history, and one `SessionCache`.
+This is the path to use when a UI needs uploaded artefacts and conversation
+follow-up to stay in scope.
+
+## Connector example
+
+Connector helpers keep the quick path small while preserving progressive disclosure. Connector tools start hidden; the model must call `load_connectors` before it can use them.
+
+```python
+from data_harness import Agent
+from data_harness.providers.anthropic import AnthropicAdapter
+
+adapter = AnthropicAdapter(model="claude-sonnet-4-6")
+agent = Agent(adapter=adapter, system="You are a data analyst.")
+
+market_data = agent.connector(
+    "market_data",
+    description="Market data tools.",
+)
+
+
+def fetch_ohlcv(symbol: str) -> list[dict]:
+    return [{"symbol": symbol, "close": 101.2}]
+
+
+market_data.tool(
+    fetch_ohlcv,
+    description="Fetch OHLCV data for a ticker.",
+)
+
+result = agent.run("Load market_data and inspect AAPL.")
+print(result)
+```
+
+## What `Agent` composes
+
+`Agent` is a thin composition layer over the lower-level primitives:
+
+- A provider adapter translates model-provider SDK objects into the harness's normalised response types.
+- `Harness` owns the ReAct loop, messages, dispatch, reminders, and JSONL logging.
+- `SessionCache` stores large values as handles plus compact snapshots.
+- `AgentSession` keeps a chat-style harness and cache alive across follow-up questions.
+- `python_interpreter` is the controlled execution surface; there is no bash tool.
+- `list_variables` exposes cache handles without dumping raw payloads.
+- `ConnectorRegistry` keeps connector tools hidden until loaded.
+- `Planner` reminders and subagents are opt-in helpers, not a second runtime.
+
+For explicit wiring, read [examples/advanced_wiring.py](examples/advanced_wiring.py). The future `learn-data-harness` repository will provide the smaller, linear teaching guide once this SDK surface has stabilised.
+
+Run the advanced example - it loads a checked-in FRED unemployment-rate sample, runs analysis, uses subagents and the planner (requires `ANTHROPIC_API_KEY`):
+
+```bash
+uv run python examples/advanced_wiring.py
+```
+
+Run tests:
+
+```bash
+uv run pytest tests/ -v
+uv run pytest tests/smoke_tests.py -m live -v  # requires OPENAI_API_KEY
+```
+
+---
+
+## Project structure
+
+```
+data_harness/
+  loop.py          # Harness: the core ReAct loop
+  cache.py         # SessionCache: handle/snapshot storage
+  providers/       # Normalised adapter interface (Anthropic and OpenAI)
+  tools/
+    interpreter.py # Sandboxed Python executor
+    connectors.py  # Progressive connector registry
+    planner.py     # Plan/nag tool
+    subagent.py    # Isolated subagent spawning
+    variables.py   # list_variables tool
+  types.py         # Shared types: Message, ToolSpec, ContentBlock
+  logger.py        # JSONL turn logging
+  observe.py       # Latency measurement
+examples/
+  quickstart.py        # Minimal Agent path
+  advanced_wiring.py   # Explicit Harness wiring
+  data/                # Small public sample data for the advanced demo
+```
+
+---
+
+## Sandbox disclaimer
+
+The Python interpreter uses AST checks and restricted globals to reduce accidental misuse. It is not a container sandbox and should not be treated as safe for untrusted input.
+
+---
+
+## License
+
+MIT

data_harness-0.1.3/data_harness/__init__.py

@@ -0,0 +1,48 @@
+from data_harness.agent import Agent, AgentSession, AsyncAgent, AsyncAgentSession
+from data_harness.exceptions import (
+    MaxTurnsExceeded,
+    SubagentRecursionError,
+    ToolNotFoundError,
+)
+from data_harness.loop import AsyncHarness
+from data_harness.providers.base import (
+    AsyncProviderAdapter,
+    NormalizedResponse,
+    ProviderAdapter,
+    StopReason,
+)
+from data_harness.result import CacheStorageInfo, RunResult, Usage
+from data_harness.types import (
+    ContentBlock,
+    Message,
+    TextBlock,
+    ToolAnnotations,
+    ToolResultBlock,
+    ToolSpec,
+    ToolUseBlock,
+)
+
+__all__ = [
+    "Agent",
+    "AgentSession",
+    "AsyncAgent",
+    "AsyncAgentSession",
+    "AsyncHarness",
+    "AsyncProviderAdapter",
+    "CacheStorageInfo",
+    "ContentBlock",
+    "MaxTurnsExceeded",
+    "Message",
+    "NormalizedResponse",
+    "ProviderAdapter",
+    "RunResult",
+    "StopReason",
+    "SubagentRecursionError",
+    "TextBlock",
+    "ToolAnnotations",
+    "ToolNotFoundError",
+    "ToolResultBlock",
+    "ToolSpec",
+    "ToolUseBlock",
+    "Usage",
+]