Metadata-Version: 2.4
Name: claubee
Version: 0.1.0
Summary: Sequential AI pipeline runner with per-step model switching and interactive error recovery
Project-URL: Homepage, https://github.com/TroBeeOne/claubee
Project-URL: Issues, https://github.com/TroBeeOne/claubee/issues
Project-URL: Changelog, https://github.com/TroBeeOne/claubee/CHANGELOG.md
Author: TroBeeOne
License: MIT
Keywords: ai,automation,claude,claude-code,llm,ollama,pipeline
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: claude-code-sdk>=0.0.14
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Description-Content-Type: text/markdown

# Claubee 

**Sequential AI pipeline runner with per-step model switching and interactive error recovery.**

Claubee lets you define a sequence of AI-powered steps in a single TOML file. Each step can use a different model and backend — Anthropic or Ollama — and the output of each step is automatically passed as context to the next. When a step fails, Claubee gives you an interactive menu to retry, inject a correction, edit the prompt, skip, or abort.

---

## Installation

```bash
pip install claubee
```

Requires Python 3.10+.

---

## Quick Start

1. Copy `examples/example_config.toml` to your project directory
2. Edit the steps to match your use case
3. Run:

```bash
claubee run example_config.toml
```

---

## Full Example

Here is a complete `pipeline.toml` for a real-world scenario: reviewing and documenting a codebase, then running a deep multi-stage analysis, and finally producing a build report. It demonstrates single prompts, a file-based prompt, and sub-prompts in one pipeline.

```toml
[global]
project_dir = "C:/Projects/MyApp"
context_log  = "C:/Projects/MyApp/claubee_run_context.txt"
context_mode = "full"
ollama_base_url = "http://localhost:11434"

# Step 1 — Understand the codebase with Anthropic
[[steps]]
name = "Understand Codebase"
backend = "anthropic"
model = "claude-sonnet-4-6"
prompt = """
Read the files in this directory. Give a high-level summary of what this
project does, its architecture, key files, and any obvious technical debt.
"""
allowed_tools = ["Read", "Glob", "Grep"]
permission_mode = "acceptEdits"
stream = true
context_mode = "full"

# Step 2 — Write docs using Ollama (cheaper model for bulk writing)
[[steps]]
name = "Write Documentation"
backend = "ollama"
model = "gemma3:12b"
prompt = """
Using the architecture summary from the prior context, write a comprehensive
DOCS.md covering: Overview, Architecture, Key Components, and Developer Setup.
Save the file as DOCS.md in the project root.
"""
allowed_tools = ["Read", "Write"]
permission_mode = "acceptEdits"
stream = true
context_mode = "summary"

# Step 3 — Prompt loaded from a file in the project directory.
# REVIEW_CHECKLIST.md contains a detailed, versioned list of review criteria
# maintained by the team — keeping it outside the TOML makes it easy to update
# without touching the pipeline config.
[[steps]]
name = "Security and Quality Review"
backend = "anthropic"
model = "claude-sonnet-4-6"
prompt = """
Read the file REVIEW_CHECKLIST.md in this directory. It contains the full
review criteria for this project. Follow every item in that checklist exactly,
examining the relevant source files for each point. Write your findings to
REVIEW_REPORT.md.
"""
allowed_tools = ["Read", "Write", "Glob", "Grep"]
permission_mode = "acceptEdits"
stream = true
context_mode = "summary"

# Step 4 — Multi-stage build analysis using sub_prompts.
# Each sub-prompt runs in sequence; Anthropic caches the shared prefix,
# keeping token costs lower than four independent calls would be.
[[steps]]
name = "Build and Test Analysis"
backend = "anthropic"
model = "claude-sonnet-4-6"
sub_prompts = [
    "Run `dotnet build` and capture the full output. List every warning and error.",
    "For each build error found, locate the relevant source file and explain the root cause.",
    "Attempt to fix the errors. Apply the minimal change needed for each one.",
    "Run `dotnet build` again to confirm the fixes. Report which errors were resolved and which remain.",
]
session_summary_prompt = """
Summarise the build result: how many errors were found, how many were fixed,
and what (if anything) still needs manual attention. Keep it under 150 words.
"""
allowed_tools = ["Read", "Edit", "Bash", "Glob"]
permission_mode = "acceptEdits"
stream = true
context_mode = "full"

# Step 5 — Final summary with Ollama
[[steps]]
name = "Final Summary"
backend = "ollama"
model = "gemma3:12b"
prompt = """
Review all prior context from this pipeline run. Write a concise executive
summary covering: what the project does, documentation produced, review
findings, build status, and any outstanding issues. Save it as SUMMARY.md.
"""
allowed_tools = ["Read", "Write"]
permission_mode = "acceptEdits"
stream = true
context_mode = "none"
```

Run it with:

```bash
claubee run pipeline.toml
```

Resume from a specific step after a failure:

```bash
claubee run pipeline.toml --start-from "Build and Test Analysis"
```

The rolling context is saved to `claubee_run_context.txt` after each step completes, so `--start-from` can pick up exactly where the pipeline left off.

---

## How It Works

Claubee uses the **Claude Code SDK** as its single runner for all steps. Backend switching between Anthropic and Ollama is handled entirely via environment variables — no separate runner code per backend.

Before each step, Claubee sets the appropriate env vars:

- **Anthropic:** uses `ANTHROPIC_API_KEY` (or your Claude Code login session)
- **Ollama:** sets `ANTHROPIC_AUTH_TOKEN=ollama`, `ANTHROPIC_BASE_URL=http://localhost:11434`, and clears the API key

The SDK sees a valid Anthropic-compatible API regardless of which backend is active. After each step, the previous env state is restored exactly.

---

## Config Reference

### `[global]` section

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `project_dir` | string | yes | — | Working directory for all steps |
| `context_log` | string | no | `./claubee_context.txt` | File path to save rolling context after each step |
| `context_mode` | string | no | `"full"` | Default context strategy: `"full"`, `"summary"`, or `"none"` |
| `ollama_base_url` | string | no | `"http://localhost:11434"` | Base URL for Ollama — change if running on a different host |

### `[[steps]]` entries

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `name` | string | yes | — | Display name for banners and error messages |
| `backend` | string | yes | — | `"anthropic"` or `"ollama"` |
| `model` | string | yes | — | Model ID (e.g. `"claude-sonnet-4-6"`, `"gemma3:12b"`) |
| `prompt` | string | one of | — | Single prompt for this step. Mutually exclusive with `sub_prompts`. |
| `sub_prompts` | list[string] | one of | — | Multiple sequential prompts sharing session context. Anthropic only. |
| `session_summary_prompt` | string | no | — | Optional final prompt whose output is appended to the pipeline context (used with `sub_prompts`) |
| `allowed_tools` | list[string] | no | `["Read"]` | Claude Code SDK tools pre-approved for this step |
| `permission_mode` | string | no | `"acceptEdits"` | SDK permission mode: `"acceptEdits"`, `"bypassPermissions"`, `"dontAsk"`, `"default"` |
| `stream` | bool | no | `true` | Stream output token-by-token to the terminal |
| `context_mode` | string | no | inherits global | `"full"` / `"summary"` / `"none"` — how this step's output is appended to pipeline context |

### Sub-prompts

A step with `sub_prompts` runs multiple prompts sequentially within the same conceptual session. Each sub-prompt receives the accumulated output of all prior sub-prompts as context. This is useful for multi-stage reasoning where each stage builds on the previous one.

Only the final sub-prompt's output is appended to the rolling pipeline context for downstream steps — unless `session_summary_prompt` is defined, in which case that output is used instead.

```toml
[[steps]]
name = "Deep Analysis"
backend = "anthropic"
model = "claude-sonnet-4-6"
sub_prompts = [
    "Identify the three most complex areas of this codebase.",
    "For each area, explain the risks and complexity drivers.",
    "Propose the single most impactful refactoring.",
]
session_summary_prompt = "Summarise all three areas and the top recommendation in 100 words."
allowed_tools = ["Read", "Glob", "Grep"]
context_mode = "summary"
```

---

## Backend Setup

### Anthropic

Either set your API key:
```bash
export ANTHROPIC_API_KEY=sk-ant-...
claubee run config.toml
```

Or pass it directly:
```bash
claubee run config.toml --api-key sk-ant-...
```

Or omit it entirely — if you're logged in to Claude Code, the SDK uses your session automatically.

### Ollama

1. Install Ollama: https://ollama.com
2. Pull a model: `ollama pull gemma3:12b`
3. Start the server: `ollama serve`
4. Use `backend = "ollama"` in your step config

If Ollama runs on a non-default host or port, set `ollama_base_url` in `[global]`.

---

## CLI Reference

```
claubee run <config_file> [OPTIONS]
```

| Option | Description |
|---|---|
| `--api-key TEXT` | Anthropic API key. Overrides `ANTHROPIC_API_KEY` env var. |
| `--start-from TEXT` | Step name to resume from. Loads saved context log automatically. |
| `--dry-run` | Print assembled prompts and config without calling any API. |
| `--help` | Show usage. |

### Examples

```bash
# Standard run
claubee run myconfig.toml

# With explicit API key
claubee run myconfig.toml --api-key sk-ant-abc123

# Resume from a specific step (loads context log automatically)
claubee run myconfig.toml --start-from "Build and Test"

# Preview what would run without calling any API
claubee run myconfig.toml --dry-run
```

---

## Error Recovery

When a step fails, Claubee displays an interactive menu:

```
╔══════════════════════════════════════════════════════════╗
║  STEP FAILED: Build and Test  (step 3 of 4)             ║
╠══════════════════════════════════════════════════════════╣
║  Backend: anthropic  |  Model: claude-sonnet-4-6        ║
║                                                          ║
║  Error:                                                  ║
║  CS0103: The name 'AuthService' does not exist           ║
╚══════════════════════════════════════════════════════════╝

What would you like to do?
  [r] Retry the step as-is
  [i] Inject a correction and retry
  [e] Edit the step prompt and retry
  [s] Skip this step and continue
  [q] Quit pipeline
```

- **Retry (`r`)** — reruns the step unchanged; useful for transient failures
- **Inject (`i`)** — prepend a correction note and the error to the prompt before retrying
- **Edit (`e`)** — interactively rewrite the step prompt before retrying
- **Skip (`s`)** — mark the step as skipped and move on; a skip note is added to context
- **Quit (`q`)** — save context and exit with code 1

If a retry also fails, the menu is shown again. There is no automatic retry limit.

---

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes — keep the code simple and readable
4. Run `pytest tests/` to verify
5. Open a pull request

The codebase is intentionally straightforward. Each concern lives in a single file and the data flow is linear: config → preflight → pipeline → steps → context.
