tau-ai 0.1.0__tar.gz

tau_ai-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: Deploy documentation
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+defaults:
+  run:
+    working-directory: website
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build documentation
+        run: bun run build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: website/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

tau_ai-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,65 @@
+name: Publish Python package
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "v*"
+  release:
+    types:
+      - published
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version-file: .python-version
+
+      - name: Check whether version is already on PyPI
+        id: pypi
+        run: |
+          NAME=$(python - <<'PY'
+          import tomllib
+          print(tomllib.load(open('pyproject.toml', 'rb'))['project']['name'])
+          PY
+          )
+          VERSION=$(python - <<'PY'
+          import tomllib
+          print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])
+          PY
+          )
+          STATUS=$(curl -s -o /dev/null -w '%{http_code}' "https://pypi.org/pypi/${NAME}/${VERSION}/json")
+          echo "name=${NAME}" >> "$GITHUB_OUTPUT"
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          if [ "$STATUS" = "200" ]; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+            echo "${NAME} ${VERSION} already exists on PyPI; skipping publish."
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build package
+        if: steps.pypi.outputs.exists != 'true'
+        run: uv build
+
+      - name: Publish package
+        if: steps.pypi.outputs.exists != 'true'
+        run: uv publish

tau_ai-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Astro / Starlight docs site (website/)
+website/node_modules/
+website/dist/
+website/.astro/

tau_ai-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

tau_ai-0.1.0/AGENTS.md

@@ -0,0 +1,74 @@
+# Tau Agent Instructions
+
+Tau is a Python implementation of Pi's minimalist coding-agent harness architecture. The goal is to develop it incrementally, with each phase clearly documented and tested.
+
+## Project Roadmap
+
+The implementation roadmap is tracked in GitHub issue #1:
+
+- https://github.com/alejandro-ao/tau/issues/1
+
+Use that issue as the primary reference for phase ordering and architectural intent.
+
+## Architecture Principles
+
+Preserve Pi's core separation of concerns:
+
+```text
+AgentHarness = reusable agent brain
+AgentSession = coding-agent environment
+TUI = one possible frontend
+```
+
+Tau should be organized around these layers:
+
+```text
+tau_ai      provider/model streaming layer
+tau_agent   portable agent harness, loop, tools, events, sessions
+tau_coding  CLI app, resources, skills, extensions, commands, TUI integration
+```
+
+Keep the core agent package independent of CLI, Textual, Rich rendering, session file locations, and application-specific resource loading.
+
+## TUI Direction
+
+Use Textual for the full interactive TUI, but only behind an adapter boundary. The agent harness should emit events; UI layers should consume those events.
+
+Early phases should prioritize:
+
+1. print-mode CLI
+2. Rich renderers
+3. Textual interactive app
+
+Do not let Textual become a dependency of the reusable agent harness.
+
+## Development Workflow
+
+- Work in small, documented phases.
+- Keep changes aligned with the roadmap issue.
+- Add or update docs when introducing architectural concepts.
+- Add tests for behavior before expanding features.
+- Run tests and Python commands through `uv` (for example, `uv run pytest` or `uv run python ...`) so they use the project environment.
+- Prefer simple, explicit abstractions over framework-heavy designs.
+- Keep commits atomic: one coherent feature, fix, docs update, refactor, or cleanup per commit.
+
+## Python Guidelines
+
+- Target the Python version declared in `pyproject.toml`.
+- Prefer typed dataclasses or schema models for core messages, events, tools, and sessions.
+- Keep async boundaries explicit.
+- Use fake providers and fake tools for deterministic agent-loop tests.
+- Avoid provider-specific assumptions in core agent code.
+
+## Documentation Expectations
+
+Each substantial phase should leave behind beginner-friendly notes under `dev-notes/` (build journals, design docs, ADRs), explaining:
+
+- what was added
+- why it exists
+- how it maps to Pi's design
+- how to test or use it
+
+When a phase adds or changes user-facing behavior, also update the published docs
+under `website/src/content/docs/` (the "Use Tau" guides and reference).
+

tau_ai-0.1.0/PKG-INFO

@@ -0,0 +1,368 @@
+Metadata-Version: 2.4
+Name: tau-ai
+Version: 0.1.0
+Summary: A Python implementation of a minimalist Pi-style coding-agent harness.
+Project-URL: Homepage, https://twotimespi.dev
+Project-URL: Documentation, https://twotimespi.dev
+Project-URL: Repository, https://github.com/alejandro-ao/tau
+Project-URL: Issues, https://github.com/alejandro-ao/tau/issues
+Requires-Python: >=3.14
+Requires-Dist: anyio>=4.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Requires-Dist: rich>=13.0
+Requires-Dist: textual>=1.0
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/assets/tau-header.svg" alt="Tau — a Python coding-agent harness inspired by Pi" width="100%" />
+</p>
+
+<p align="center">
+  <strong>A minimalist coding-agent harness in Python, inspired by Pi and built as a teaching project.</strong>
+</p>
+
+<p align="center">
+  <a href="https://twotimespi.dev/">Documentation</a>
+  ·
+  <a href="docs/getting-started.md">Getting started</a>
+  ·
+  <a href="docs/architecture/index.md">Architecture notes</a>
+  ·
+  <a href="https://github.com/alejandro-ao/tau/issues/1">Roadmap</a>
+</p>
+
+---
+
+## What is Tau?
+
+Tau is a Python implementation of the minimalist coding-agent harness architecture
+popularized by **Pi**. It is both:
+
+1. a usable terminal coding agent, and
+2. a readable, phase-by-phase reference implementation for learning how coding
+   agents are assembled.
+
+The project intentionally keeps the core pieces small and explicit: model
+providers stream events, an agent loop turns those events into tool execution and
+transcript updates, a reusable harness owns state, and the coding app adds local
+files, shell tools, sessions, skills, commands, and terminal frontends.
+
+```text
+tau_ai       provider/model streaming layer
+tau_agent    portable agent harness, loop, tools, events, sessions
+tau_coding   CLI app, resources, skills, commands, sessions, UI integration
+```
+
+The central design boundary is:
+
+```text
+AgentHarness = reusable agent brain
+AgentSession = coding-agent environment
+TUI          = one possible frontend
+```
+
+Tau should make the architecture legible. If you want to understand how a coding
+agent works without starting from a large production codebase, this repository is
+for you.
+
+## Why Tau exists
+
+Tau is being built as an effort to teach how to create coding agents.
+
+The philosophy is:
+
+- **Small layers beat magic.** Each package has a clear job and can be explained
+  independently.
+- **Events are the contract.** The agent harness emits provider-neutral events;
+  renderers and TUIs consume them.
+- **The core stays portable.** `tau_agent` does not depend on Textual, Rich,
+  shell config directories, slash commands, or application-specific resources.
+- **Tools are ordinary typed functions.** File and shell capabilities are exposed
+  through explicit schemas and deterministic result objects.
+- **Sessions are durable and inspectable.** Tau stores append-only JSONL session
+  transcripts under `~/.tau/sessions/`.
+- **Documentation follows implementation.** The project is developed in small,
+  documented phases so readers can trace how the system grows.
+
+Pi is the design inspiration; Tau is the Python learning path.
+
+## Current capabilities
+
+Tau currently includes:
+
+- an installable `tau` console command
+- a Textual interactive TUI
+- non-interactive print mode for one-shot prompts
+- OpenAI-compatible, Anthropic, OpenAI Codex subscription, OpenRouter, and
+  Hugging Face provider support through provider configuration
+- provider retry/backoff events and thinking/reasoning deltas
+- built-in local coding tools: `read`, `write`, `edit`, and `bash`
+- durable per-project sessions and session resume
+- session tree branching and HTML/JSONL export
+- slash commands, model picker, theme picker, and autocomplete
+- skills, prompt templates, and `AGENTS.md` project-context discovery
+- context accounting, manual compaction, and optional automatic compaction
+- Rich/plain/json/transcript rendering paths for print-mode output
+- a deterministic fake provider used by tests
+
+Tau is still evolving. Expect the command surface and internals to improve as the
+roadmap progresses.
+
+## Install
+
+Tau targets the Python version declared in `pyproject.toml` and uses
+[`uv`](https://docs.astral.sh/uv/) for the recommended workflow.
+
+Install from GitHub:
+
+```bash
+uv tool install tau-ai
+tau --version
+```
+
+Install from a local checkout:
+
+```bash
+git clone https://github.com/alejandro-ao/tau.git
+cd tau
+uv tool install --editable .
+tau --version
+```
+
+For development:
+
+```bash
+uv sync --dev
+uv run tau --version
+```
+
+## First run
+
+Start the interactive terminal UI:
+
+```bash
+tau
+```
+
+Start the TUI and submit the first prompt immediately:
+
+```bash
+tau "explain this repository"
+```
+
+Run a one-shot non-interactive prompt:
+
+```bash
+tau -p "summarize the architecture"
+```
+
+Choose a configured provider/model:
+
+```bash
+tau --provider openai --model gpt-4.1 "review this codebase"
+tau --provider local --model qwen -p "list the main modules"
+```
+
+Use another working directory for coding tools:
+
+```bash
+tau --cwd /path/to/project "find the CLI entry point"
+```
+
+## Configure a model provider
+
+The easiest path is from inside the TUI:
+
+```text
+/login
+/login openai
+/login openai-codex
+/logout
+/logout openai
+/model
+```
+
+`/login` can save API-key credentials for built-in providers or authenticate an
+OpenAI Codex subscription account with OAuth. Credentials are stored in
+`~/.tau/credentials.json` with private file permissions. Provider metadata lives
+in `~/.tau/providers.json`. `/logout` removes only credentials saved in Tau's
+`credentials.json`; environment variables and provider configuration are
+unchanged.
+
+You can also configure an OpenAI-compatible provider from the CLI:
+
+```bash
+tau --provider local \
+  --base-url http://localhost:11434/v1 \
+  --api-key-env LOCAL_API_KEY \
+  --model qwen \
+  setup
+```
+
+Then run:
+
+```bash
+export LOCAL_API_KEY="..."
+tau --provider local
+```
+
+Useful provider commands:
+
+```bash
+tau providers
+```
+
+See [docs/providers.md](docs/providers.md) and
+[docs/configuration.md](docs/configuration.md) for details.
+
+## Working in the TUI
+
+Common slash commands:
+
+| Command | Purpose |
+| --- | --- |
+| `/login [provider]` | Save or refresh provider credentials. |
+| `/logout [provider]` | Remove Tau-saved provider credentials. |
+| `/model` | Choose the active provider/model. |
+| `/scoped-models` | Pick models available for quick cycling. |
+| `/session` | Show session and context information. |
+| `/resume [session-id]` | Resume a previous session. |
+| `/tree` | Branch from a previous session entry. |
+| `/name <new name>` | Rename the current session. |
+| `/compact <summary>` | Replace active context with a manual summary. |
+| `/export [--format html\|jsonl] [destination]` | Export the current session. |
+| `/reload` | Reload local resources and project context. |
+| `/theme [name]` | Show or set the TUI theme. |
+| `/hotkeys` | Show common keyboard shortcuts. |
+| `/quit` | Exit the session. |
+
+Important TUI behavior:
+
+- Click anywhere in the main TUI to return keyboard focus to the prompt input.
+
+Common shortcuts:
+
+| Shortcut | Action |
+| --- | --- |
+| `Enter` | Submit prompt. |
+| `Shift+Enter` | Insert newline. |
+| `Alt+Enter` | Queue a follow-up while the agent is running. |
+| `Esc` | Cancel active run. |
+| `Ctrl+K` | Open slash-command completions. |
+| `Ctrl+R` | Open session picker. |
+| `Shift+Tab` | Cycle thinking mode. |
+| `Ctrl+T` | Toggle thinking-token display. |
+| `Ctrl+O` | Collapse or expand tool output. |
+| `Ctrl+P` | Cycle scoped models. |
+| `Ctrl+D` | Quit. |
+
+## Sessions, resources, and files
+
+Tau stores durable app state in your home directory:
+
+```text
+~/.tau/providers.json       provider metadata
+~/.tau/credentials.json     saved API keys and OAuth credentials
+~/.tau/tui.json             TUI theme/keybinding settings
+~/.tau/sessions/            append-only JSONL session transcripts
+~/.tau/skills/              user Tau skills
+~/.tau/prompts/             user prompt templates
+~/.tau/AGENTS.md            user Tau instructions
+```
+
+Tau also reads user-level `.agents` resources and project-local resources from
+the active working directory, including `AGENTS.md`, `.tau/`, and `.agents/`
+locations. This lets a project teach Tau how it should behave without changing
+Tau's core harness.
+
+## Use Tau as a library
+
+Tau's reusable brain lives in `tau_agent`:
+
+```python
+from tau_agent import AgentHarness, AgentHarnessConfig
+
+harness = AgentHarness(
+    AgentHarnessConfig(
+        provider=provider,
+        model="my-model",
+        system="You are a helpful coding agent.",
+        tools=tools,
+    )
+)
+
+async for event in harness.prompt("Explain this package"):
+    print(event)
+```
+
+That harness is deliberately independent of the CLI/TUI. You can build another
+frontend by consuming the same event stream.
+
+## Development
+
+Set up the repository:
+
+```bash
+uv sync --dev
+```
+
+Run checks:
+
+```bash
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+```
+
+Run Tau locally:
+
+```bash
+uv run tau
+uv run tau -p "explain this repo"
+```
+
+Run the documentation site (Astro Starlight, in `website/`):
+
+```bash
+cd website
+bun install
+bun run dev
+```
+
+Then open `http://localhost:4321/tau/`. Build the static site with `bun run build` (output in `website/dist/`).
+
+## Documentation
+
+The user-facing docs are published at <https://twotimespi.dev/>.
+Their source lives in `website/src/content/docs/`:
+
+- [What is Tau?](website/src/content/docs/what-is-tau.md)
+- [Quickstart](website/src/content/docs/quickstart.md)
+- [Core concepts](website/src/content/docs/concepts.md)
+- Guides — [the TUI](website/src/content/docs/guides/tui.md),
+  [sessions](website/src/content/docs/guides/sessions.md),
+  [providers & models](website/src/content/docs/guides/providers-and-models.md),
+  [skills & prompts](website/src/content/docs/guides/skills-and-prompts.md),
+  [context](website/src/content/docs/guides/context.md)
+- Reference — [CLI](website/src/content/docs/reference/cli.md),
+  [slash commands](website/src/content/docs/reference/slash-commands.md),
+  [keybindings](website/src/content/docs/reference/keybindings.md),
+  [configuration](website/src/content/docs/reference/configuration.md),
+  [tools](website/src/content/docs/reference/tools.md)
+- How Tau works — [architecture](website/src/content/docs/internals/architecture.md),
+  [the agent loop](website/src/content/docs/internals/agent-loop.md)
+
+Contributor build journals (phase notes, design docs, ADRs) live in
+[`dev-notes/`](dev-notes/README.md) and are intentionally not published.
+
+## Project status
+
+Tau is under active development. The implementation roadmap is tracked in
+[GitHub issue #1](https://github.com/alejandro-ao/tau/issues/1), and the notes
+under [`dev-notes/architecture/`](dev-notes/architecture/) record the completed phases.
+
+The goal is not to hide complexity. The goal is to make each part of a coding
+agent visible, testable, and understandable.