Rebrand Python bindings as native Python package (#440)

## Summary
- Rewrote `crates/bashkit-python/README.md` to present bashkit as a
native Python package (tiktoken-style), not "bindings"
- Moved Rust/Bashkit core mention to a "How it works" section at the
bottom
- Replaced all "bindings" references with "package" across specs,
AGENTS.md, CI workflows, Cargo.toml, lib.rs, and tests

## Test plan
- [ ] Verify README renders correctly on PyPI/GitHub
- [ ] `just check` passes (no functional changes)
- [ ] CI green

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: chaliy

.github/workflows/publish-python.yml

@@ -1,4 +1,4 @@
-# PyPI publishing workflow for bashkit Python bindings
+# PyPI publishing workflow for bashkit Python package
 # Builds pre-compiled wheels for all major platforms and publishes to PyPI.
 # Triggered alongside publish.yml on GitHub Release or manual dispatch.
 # Adapted from https://github.com/pydantic/monty CI wheel-building pattern.

.github/workflows/python.yml

@@ -1,4 +1,4 @@
-# CI for bashkit Python bindings
+# CI for bashkit Python package
 # Builds the native extension via maturin and runs pytest on each PR.
 # Complements publish-python.yml (release-only) with per-PR validation.
 

AGENTS.md

@@ -39,7 +39,7 @@ Fix root cause. Unsure: read more code; if stuck, ask w/ short options. Unrecogn
 | 011-python-builtin | Embedded Python via Monty, security, resource limits |
 | 012-eval | LLM evaluation harness, dataset format, scoring |
 | 012-maintenance | Pre-release maintenance checklist |
-| 013-python-package | Python bindings, PyPI wheels, platform matrix |
+| 013-python-package | Python package, PyPI wheels, platform matrix |
 | 014-scripted-tool-orchestration | Compose ToolDef+callback pairs into OrchestratorTool via bash scripts |
 
 ### Documentation
@@ -88,7 +88,7 @@ just pre-pr       # Pre-PR checks
 
 ### Python
 
-- Python bindings in `crates/bashkit-python/`
+- Python package in `crates/bashkit-python/`
 - Linter/formatter: `ruff` (config in `pyproject.toml`)
 - `ruff check crates/bashkit-python` and `ruff format --check crates/bashkit-python`
 - Tests: `pytest crates/bashkit-python/tests/ -v` (requires `maturin develop` first)

crates/bashkit-python/Cargo.toml

@@ -1,4 +1,4 @@
-# Python bindings for Bashkit
+# Bashkit Python package
 # Exposes Bashkit as a Python module via PyO3
 
 [package]
@@ -8,7 +8,7 @@ edition.workspace = true
 license.workspace = true
 authors.workspace = true
 repository.workspace = true
-description = "Python bindings for Bashkit virtual bash interpreter"
+description = "A sandboxed bash interpreter for AI agents"
 
 [lib]
 crate-type = ["cdylib"]
@@ -19,7 +19,7 @@ doc = false  # Python extension, no Rust docs needed
 # Bashkit core
 bashkit = { path = "../bashkit", features = ["scripted_tool"] }
 
-# PyO3 for Python bindings
+# PyO3 native extension
 pyo3 = { workspace = true }
 pyo3-async-runtimes = { workspace = true }
 

crates/bashkit-python/README.md

@@ -1,30 +1,36 @@
-# Bashkit Python Bindings
+# Bashkit
 
-Python bindings for [Bashkit](https://github.com/everruns/bashkit) - a virtual bash interpreter for AI agents.
+A sandboxed bash interpreter for AI agents.
+
+```python
+from bashkit import BashTool
+
+tool = BashTool()
+result = tool.execute_sync("echo 'Hello, World!'")
+print(result.stdout)  # Hello, World!
+```
 
 ## Features
 
-- **Sandboxed, in-process execution**: All commands run in isolation with a virtual filesystem
-- **68+ built-in commands**: echo, cat, grep, sed, awk, jq, curl, find, and more
-- **Full bash syntax**: Variables, pipelines, redirects, loops, functions, arrays
-- **Resource limits**: Protect against infinite loops and runaway scripts
-- **LangChain integration**: Ready-to-use tool for LangChain agents
+- **Sandboxed execution** — all commands run in-process with a virtual filesystem, no containers needed
+- **68+ built-in commands** — echo, cat, grep, sed, awk, jq, curl, find, and more
+- **Full bash syntax** — variables, pipelines, redirects, loops, functions, arrays
+- **Resource limits** — protect against infinite loops and runaway scripts
+- **Framework integrations** — LangChain, PydanticAI, and Deep Agents
 
 ## Installation
 
 ```bash
-# From PyPI (when published)
 pip install bashkit
 
-# With LangChain support
+# With framework support
 pip install 'bashkit[langchain]'
-
-# From source
-pip install maturin
-maturin develop
+pip install 'bashkit[pydantic-ai]'
 ```
 
-## Quick Start
+## Usage
+
+### Async
 
 ```python
 import asyncio
@@ -51,29 +57,17 @@ async def main():
 asyncio.run(main())
 ```
 
-## LangChain Integration
+### Sync
 
 ```python
-from bashkit.langchain import create_bash_tool
-from langchain.agents import create_agent
-
-# Create tool
-bash_tool = create_bash_tool()
-
-# Create agent
-agent = create_agent(
-    model="claude-sonnet-4-20250514",
-    tools=[bash_tool],
-    system_prompt="You are a helpful assistant with bash skills."
-)
+from bashkit import BashTool
 
-# Run
-result = agent.invoke({
-    "messages": [{"role": "user", "content": "Create a file with today's date"}]
-})
+tool = BashTool()
+result = tool.execute_sync("echo 'Hello!'")
+print(result.stdout)
 ```
 
-## Configuration
+### Configuration
 
 ```python
 tool = BashTool(
@@ -84,35 +78,68 @@ tool = BashTool(
 )
 ```
 
-## Synchronous API
+### Scripted Tool Orchestration
+
+Compose multiple tools into a single bash-scriptable interface:
 
 ```python
-from bashkit import BashTool
+from bashkit import ScriptedTool
 
-tool = BashTool()
-result = tool.execute_sync("echo 'Hello!'")
-print(result.stdout)
+tool = ScriptedTool("api")
+tool.add_tool("greet", "Greet a user", callback=lambda p, s=None: f"hello {p.get('name', 'world')}")
+result = tool.execute_sync("greet --name Alice")
+print(result.stdout)  # hello Alice
+```
+
+### LangChain
+
+```python
+from bashkit.langchain import create_bash_tool
+
+bash_tool = create_bash_tool()
+# Use with any LangChain agent
+```
+
+### PydanticAI
+
+```python
+from bashkit.pydantic_ai import create_bash_tool
+
+bash_tool = create_bash_tool()
+# Use with any PydanticAI agent
 ```
 
 ## API Reference
 
 ### BashTool
 
-- `execute(commands: str) -> ExecResult`: Execute commands asynchronously
-- `execute_sync(commands: str) -> ExecResult`: Execute commands synchronously
-- `description() -> str`: Get tool description
-- `help() -> str`: Get LLM documentation
-- `input_schema() -> str`: Get JSON input schema
-- `output_schema() -> str`: Get JSON output schema
+- `execute(commands: str) -> ExecResult` — execute commands asynchronously
+- `execute_sync(commands: str) -> ExecResult` — execute commands synchronously
+- `reset()` — reset interpreter state
+- `description() -> str` — tool description for LLM integration
+- `help() -> str` — detailed documentation
+- `input_schema() -> str` — JSON input schema
+- `output_schema() -> str` — JSON output schema
 
 ### ExecResult
 
-- `stdout: str`: Standard output
-- `stderr: str`: Standard error
-- `exit_code: int`: Exit code (0 = success)
-- `error: Optional[str]`: Error message if execution failed
-- `success: bool`: True if exit_code == 0
-- `to_dict() -> dict`: Convert to dictionary
+- `stdout: str` — standard output
+- `stderr: str` — standard error
+- `exit_code: int` — exit code (0 = success)
+- `error: Optional[str]` — error message if execution failed
+- `success: bool` — True if exit_code == 0
+- `to_dict() -> dict` — convert to dictionary
+
+### ScriptedTool
+
+- `add_tool(name, description, callback, schema=None)` — register a tool
+- `execute(script: str) -> ExecResult` — execute script asynchronously
+- `execute_sync(script: str) -> ExecResult` — execute script synchronously
+- `env(key: str, value: str)` — set environment variable
+
+## How it works
+
+Bashkit is built on top of [Bashkit core](https://github.com/everruns/bashkit), a bash interpreter written in Rust. The Python package provides a native extension for fast, sandboxed execution without spawning subprocesses or containers.
 
 ## License
 

crates/bashkit-python/bashkit/__init__.py

@@ -1,12 +1,10 @@
 """
-Bashkit Python Bindings
-
-A sandboxed bash interpreter for AI agents with virtual filesystem.
+Bashkit — a sandboxed bash interpreter for AI agents.
 
 Example:
     >>> from bashkit import BashTool
     >>> tool = BashTool()
-    >>> result = await tool.execute("echo 'Hello, World!'")
+    >>> result = tool.execute_sync("echo 'Hello, World!'")
     >>> print(result.stdout)
     Hello, World!
 

crates/bashkit-python/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "maturin"
 [project]
 name = "bashkit"
 dynamic = ["version"]
-description = "Python bindings for Bashkit - a sandboxed bash interpreter for AI agents"
+description = "A sandboxed bash interpreter for AI agents"
 readme = "README.md"
 license = { text = "MIT" }
 requires-python = ">=3.9"

crates/bashkit-python/src/lib.rs

@@ -1,4 +1,4 @@
-//! Python bindings for Bashkit
+//! Bashkit Python package
 //!
 //! Exposes the Bash interpreter and ScriptedTool as Python classes for use in
 //! AI agent frameworks. BashTool provides stateful execution (filesystem persists

crates/bashkit-python/tests/test_bashkit.py

@@ -1,4 +1,4 @@
-"""Tests for bashkit Python bindings."""
+"""Tests for bashkit Python package."""
 
 import json
 

specs/001-architecture.md

@@ -118,7 +118,7 @@ impl BashTool {
 ### Single crate vs workspace
 Rejected single crate because:
 - CLI binary would bloat the library
-- Future Python bindings need separate crate
+- Python package needs separate crate
 - Cleaner separation of concerns
 
 ### Sync vs async filesystem