Shepherd

https://docs.shepherd-agents.ai
Admin
Shepherd is a framework for programming meta-agents in Python, allowing users to write agents as...
Tokens:9,119
Snippets:141
Trust Score:2.1
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Shepherd AI

Source: https://docs.shepherd-agents.ai/start

Install the Shepherd AI library using pip.

```bash
pip install shepherd-ai

```

--------------------------------

### Expected Output for Hello World Example

Source: https://docs.shepherd-agents.ai/start

This is the expected output when running the 'hello.py' script. It indicates the successful completion of the 'login' feature implementation, including details about retries due to test failures.

```text
Login feature landed. The worker's first attempt failed 2 tests, so oversee reverted that step and retried; the retry passed all 41.

```

--------------------------------

### Run the Shepherd Example Twice

Source: https://docs.shepherd-agents.ai/guides/deterministic-demo

Execute the Python script twice to verify deterministic output. This command assumes the script is saved as 'hello.py'.

```bash
python hello.py
python hello.py

```

--------------------------------

### Expected Identical Output from Deterministic Runs

Source: https://docs.shepherd-agents.ai/guides/deterministic-demo

This is the expected output when running the Shepherd example twice with the deterministic offline provider. The output should be identical character for character.

```text
- Shepherd turns typed Python functions into model-backed tasks.
- The docstring is the instruction; the return type is the contract.
- Runs are recorded, so behavior is debuggable after the fact.


```

--------------------------------

### Run a Task with Whole-Run Read-Only Permissions

Source: https://docs.shepherd-agents.ai/concepts/permissions

This example demonstrates how to enforce read-only access for an entire run by passing the 'may="ReadOnly"' argument. This permission is compiled into the jail and enforced at the syscall level.

```python
run = workspace.run(task, repo=workspace.git_repo(), may="ReadOnly")
```

--------------------------------

### Run the Application

Source: https://docs.shepherd-agents.ai/tutorials/first-shepherd-app

Execute the main application file to run the Shepherd tasks within the defined workspace.

```bash
python app.py
```

--------------------------------

### Run a Task with Named Bindings

Source: https://docs.shepherd-agents.ai/concepts/permissions

This code demonstrates how to execute a task using a dictionary of named bindings, allowing the task to access specific repository roots.

```python
run = workspace.run(task, bindings={"docs": docs, "backend": backend})
```

--------------------------------

### Define a Workspace and Run Tasks

Source: https://docs.shepherd-agents.ai/tutorials/first-shepherd-app

Use `sp.workspace` to define the execution context and pin a model for all tasks within the block. Tasks remain model-agnostic.

```python
with sp.workspace(model="claude:sonnet-4-5"):
    triage = triage_change(SAMPLE_DIFF)
    review = review_change(SAMPLE_DIFF)
```

--------------------------------

### Sample Diff for Authentication Change

Source: https://docs.shepherd-agents.ai/tutorials/first-shepherd-app

This is a sample diff illustrating a change to an admin check in an authentication file.

```diff
diff --git a/auth.py b/auth.py
@@ -42,7 +42,7 @@
-    if user.is_admin:
+    if user.is_admin or user.has_role("admin"):

```

--------------------------------

### Bind a Repository to a Workspace

Source: https://docs.shepherd-agents.ai/concepts/workspaces

Bind a repository to the current workspace using 'ws.bind()'. This allows tasks within the workspace to access and modify specified resources under permission grants. The bound repository is then passed to a run using the 'bindings' argument.

```python
ws.bind(root="backend/", name="backend")
workspace.run(task, bindings={
    "backend": backend
})
```

--------------------------------

### Shepherd CLI Usage

Source: https://docs.shepherd-agents.ai/reference/cli

Displays the main help message for the `shepherd` command, listing available options and commands. Use this to understand the overall structure and entry points of the CLI.

```bash
Usage: shepherd [OPTIONS] COMMAND [ARGS]...

  Shepherd — effect-based AI agent framework.

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  demo     Emit checked-in quickstart demo scripts.
  doctor   Check whether the current directory is ready for the quickstart.
  init     Initialize PATH as a Shepherd workspace.
  package  Create and manage Shepherd extension packages.
  run      Inspect runs and settle retained outputs; start is a fenced...
  task     Manage and inspect task-library entries.


```

--------------------------------

### Executing a Task and Inspecting its Run

Source: https://docs.shepherd-agents.ai/concepts/runs

This snippet shows how to execute a task named 'review_change' and then inspect its status and the changed paths from its changeset. This is useful for understanding the immediate outcome and produced changes of a task.

```python
run = workspace.run("review_change", repo=workspace.git_repo(), args={"diff": diff})
print(run.status)                 # the run's outcome
cs = run.changeset()              # what it produced, as a read-only view
print(cs.changed_paths)

```

--------------------------------

### Shepherd Run Command Usage

Source: https://docs.shepherd-agents.ai/reference/cli

Displays the usage instructions and available commands for the `shepherd run` CLI. Use this to understand how to inspect runs and settle retained outputs.

```bash
Usage: shepherd run [OPTIONS] COMMAND [ARGS]...

  Inspect runs and settle retained outputs; start is a fenced compatibility
  entry point.

Options:
  --help  Show this message and exit.

Commands:
  changeset                       Inspect the read-only changeset view...
  discard                         Discard one retained run output as...
  list                            List run summaries from the selected...
  output-citations                List raw run-ledger output citations...
  outputs                         List product run outputs after...
  publish-retained-workspace-output
                                  Publish or repair the retained...
  release                         Release one retained run output...
  select                          Select one retained run output into...
  show                            Show one run record from the...
  start                           Run the fenced compatibility start...
  trace                           Print the materialized trace...
  trace-revision                  Print the run-trace summary for one...
  vcscore                         Show the vcs-core citations carried...


```

--------------------------------

### Running a Task with a Specific Placement

Source: https://docs.shepherd-agents.ai/concepts/placements

This snippet demonstrates how to specify a placement for a task when running it within a workspace. The 'jail' placement enforces OS-level security for the run's body.

```python
run = workspace.run(task, bindings={...}, placement="jail")

```

--------------------------------

### Define a Workspace Context

Source: https://docs.shepherd-agents.ai/concepts/workspaces

Use a 'with' block to establish a workspace, specifying the model and root directory for tasks executed within its scope. Any code called within this block inherits the same model and root.

```python
import shepherd as sp

with sp.workspace(model="claude:sonnet-4-5", root="./my-project"):
    review = review_change(diff)
```

--------------------------------

### Run Task on a Jailed Placement

Source: https://docs.shepherd-agents.ai/guides/grant-repo-access

Execute a task with specified bindings and arguments on a 'jail' placement to enforce grants at the OS level (e.g., using Seatbelt/Landlock). This ensures writes to unauthorized paths are refused by the syscall.

```python
run = ws.run(
    apply_documented_fix,
    bindings={"docs": docs, "backend": backend},
    args={"issue": "#142"},
    placement="jail",          # writable roots compiled from the grants; Seatbelt/Landlock
)

```

--------------------------------

### Routing Tasks to Different Models Using Workspaces

Source: https://docs.shepherd-agents.ai/guides/route-tasks-to-models

Use separate 'with sp.workspace(model=...)' blocks to ensure tasks are executed by the intended models. This approach keeps tasks model-agnostic and centralizes routing logic at the call site.

```python
import shepherd as sp

# cheap, fast model for the easy classification step
with sp.workspace(model="claude:haiku-4-5"):
    triage = triage_change(diff)

# stronger model for the step that needs more judgment
with sp.workspace(model="claude:sonnet-4-5"):
    review = write_review(diff, triage)

```

--------------------------------

### Viewing Run Trace and Changeset from CLI

Source: https://docs.shepherd-agents.ai/concepts/runs

These commands demonstrate how to access the trace and changeset of a specific run using its reference from the command line interface. This is helpful for forensic analysis of task executions outside of the programmatic interface.

```bash
shepherd run trace <run-ref>           # the ordered record of every boundary crossing
shepherd run changeset <run-ref>       # what it produced (read-only)

```

--------------------------------

### Expected Output of the Application

Source: https://docs.shepherd-agents.ai/tutorials/first-shepherd-app

This is the expected output when the application runs successfully, indicating a bugfix with a high priority.

```text
bugfix/high: approve - Tightens the admin gate in auth.py by requiring an explicit role check; low blast radius, no API change.

```

--------------------------------

### Run a Task with a Single Binding

Source: https://docs.shepherd-agents.ai/concepts/permissions

When a run involves only one binding, it can be specified directly using the 'repo=' argument, simplifying the run configuration.

```python
run = workspace.run(task, repo=workspace.git_repo())
```

--------------------------------

### Bind a Repository Root with a Name

Source: https://docs.shepherd-agents.ai/concepts/permissions

This snippet shows how to bind a repository root to a specific name, which is then used to reference this binding in subsequent operations.

```python
backend = ws.bind(root="backend/", name="backend")
```

--------------------------------

### shepherd package Usage

Source: https://docs.shepherd-agents.ai/reference/cli

Displays the general usage information for the `shepherd package` command, including available options and subcommands.

```bash
Usage: shepherd package [OPTIONS] COMMAND [ARGS]...

  Create and manage Shepherd extension packages.

Options:
  --help  Show this message and exit.

Commands:
  init  Create a new Shepherd package.

```

--------------------------------

### Shepherd Task Command Usage

Source: https://docs.shepherd-agents.ai/reference/cli

Displays the usage instructions and available commands for the `shepherd task` CLI. Use this to manage and inspect task-library entries.

```bash
Usage: shepherd task [OPTIONS] COMMAND [ARGS]...

  Manage and inspect task-library entries.

Options:
  --help  Show this message and exit.

Commands:
  list      List task summaries from the selected task ledger.
  register  Register a task import path as an active task version.
  resolve   Resolve a task ref to an exact artifact lock.
  show      Show one task definition and its signature/permission surface.


```

--------------------------------

### Setting a Model Provider in a Workspace

Source: https://docs.shepherd-agents.ai/concepts/providers

Use a 'with' block to define the scope of a specific model provider for all task calls within that block. This ensures all tasks are answered by the designated model.

```python
import shepherd as sp

with sp.workspace(model="claude:sonnet-4-5"):
    ...  # every task call in here is answered by that provider + model

```

--------------------------------

### Define Task Docstrings for Guidance

Source: https://docs.shepherd-agents.ai/guides/debug-your-first-run

Required for bodyless `@sp.task` decorators to define the model-call goal. Omitting the docstring results in a `TypeError` at definition time.

```python
@sp.task
def my_task():
    """First line is the job, the rest is elaboration."""
    ...
```

--------------------------------

### Bind Repositories by Name

Source: https://docs.shepherd-agents.ai/guides/grant-repo-access

Bind repository roots to names for use in task execution. Ensure that bound roots are disjoint to prevent overlapping or nested binds.

```python
docs    = ws.bind(root="docs/",    name="docs")     # returns a GitRepo value
backend = ws.bind(root="backend/", name="backend")

```

--------------------------------

### Call Task in Workspace and Assert Typed Value

Source: https://docs.shepherd-agents.ai/guides/test-shepherd-code

Pin the offline provider and call the task within a workspace. Assert on the typed return value, not parsed text.

```python
import shepherd as sp

from app import SAMPLE_DIFF, Triage, triage_change


def test_triage_matches_contract():
    with sp.workspace(model="claude:sonnet-4-5"):
        triage = triage_change(SAMPLE_DIFF)
    assert isinstance(triage, Triage)
    assert (triage.category, triage.priority) == ("bugfix", "high")

```

--------------------------------

### Specifying a Provider for a Retained Run

Source: https://docs.shepherd-agents.ai/concepts/providers

For retained runs, specify the provider using the 'runtime' argument during the workspace.run() call. The 'static' provider offers deterministic, offline execution suitable for CI.

```python
run = workspace.run(task, repo=workspace.git_repo(),
                    runtime={"provider": "static"})   # deterministic, offline, CI-safe

```

--------------------------------

### Bodyless Task Definition

Source: https://docs.shepherd-agents.ai/concepts/tasks

Define a task with a signature and docstring. Shepherd synthesizes the model prompt and handles the delivery.

```python
import shepherd as sp

@sp.task
def review_for_security(diff: str, project: str) -> SecurityReview:
    """Identify security concerns in this code change."""


```

--------------------------------

### Task with a Body for Orchestration

Source: https://docs.shepherd-agents.ai/concepts/tasks

Use a task with a body to orchestrate multiple model interactions or combine results. `sp.deliver` is used for explicit model invocations.

```python
@sp.task
def audit_change(diff: str) -> str:
    """Audit a code change; return a one-paragraph summary."""
    full = sp.deliver(str, goal="Produce a detailed audit.")
    return sp.deliver(str, goal="Summarize the audit.", evidence=[full])


```

--------------------------------

### Define Review Dataclass and Write Review Task

Source: https://docs.shepherd-agents.ai/tutorials/first-shepherd-app

Defines the `Review` dataclass, which serves as a contract for the review output. It also defines the `write_review` task, which takes a `diff` and a `triage` object as input and returns a `Review`.

```python
@dataclass(frozen=True)
class Review:
    summary: str
    verdict: str    # approve | request-changes


@sp.task
def write_review(diff: str, triage: Triage) -> Review:
    """Write a short review for this change, given its triage."""

```

--------------------------------

### Inspect and Settle Task Output

Source: https://docs.shepherd-agents.ai/guides/grant-repo-access

Review the changes produced by a task binding using `changeset` and then settle the retained output. Settlement is a consume-once operation; subsequent calls to `select`, `release`, or `discard` for the same output will be refused.

```python
cs = run.changeset(name="backend")   # a read-only view of one binding's delta
print(cs.changed_paths)
ws.select(run.output())              # keep it; or ws.release(...) / ws.discard(...)

```

--------------------------------

### Declare Repository Access Grants in Task Signature

Source: https://docs.shepherd-agents.ai/guides/grant-repo-access

Define grants for repositories within a task signature using `May`, `ReadOnly`, and `ReadWrite`. Use `ReadOnly` for read-only access and `ReadWrite` for writable root access.

```python
from shepherd import task, May, GitRepo, ReadOnly, ReadWrite

@task
def apply_documented_fix(
    docs:    May[GitRepo, ReadOnly],   # read-only: writes refused at the OS
    backend: May[GitRepo, ReadWrite],  # writable root
    issue:   str,
) -> None: ...

```

--------------------------------

### Inspect Changeset for a Specific Binding

Source: https://docs.shepherd-agents.ai/concepts/permissions

This snippet shows how to retrieve the changes associated with a specific binding within a run. The output is 'consume-once', meaning it must be selected, released, or discarded.

```python
run.changeset(name="backend")   # what the task wrote to the backend binding
```

--------------------------------

### Define Shepherd Tasks for Implementation and Oversight

Source: https://docs.shepherd-agents.ai/guides/deterministic-demo

This Python code defines two Shepherd tasks: `implement` for feature implementation and `oversee` for running workers and handling retries. It uses type hints for permissions and task contracts.

```python
import shepherd as sp


# The signature is the permission surface: the grant on `repo` is what lets the
# task write the bound repository (see "Permissions" in the concepts docs).
@sp.task
def implement(repo: sp.May[sp.GitRepo, sp.ReadWrite], feature: str) -> str:
    """Implement the feature in the repo and report what changed."""


@sp.task
def oversee(worker: object, repo: sp.May[sp.GitRepo, sp.ReadWrite], feature: str) -> str:
    """Run the worker on the feature. If its tests fail, revert and retry, then report."""


with sp.workspace(model="claude:sonnet-4-5"):
    print(oversee(implement, repo=".", feature="login"))

```

--------------------------------

### Wrap Task Calls in a Workspace

Source: https://docs.shepherd-agents.ai/guides/debug-your-first-run

Use this when encountering a `RuntimeError` indicating tasks were called outside a workspace. It ensures tasks are executed within a defined model context.

```python
with sp.workspace(model="claude:sonnet-4-5"):
    ... 
```

--------------------------------

### Compose Review Change Function

Source: https://docs.shepherd-agents.ai/tutorials/first-shepherd-app

Composes the `write_review` task with the `triage_change` function. This composition is a standard Python function, highlighting that task composition in Shepherd is achieved through direct function calls.

```python
def review_change(diff: str) -> Review:
    return write_review(diff, triage_change(diff))

```

--------------------------------

### Define Triage Task

Source: https://docs.shepherd-agents.ai/tutorials/first-shepherd-app

Define a model-backed task for classifying code changes. The function signature and docstring serve as the contract for the language model.

```python
@sp.task
def triage_change(diff: str) -> Triage:
    """Classify this code change.

    Categories are bugfix, feature, docs, and refactor.
    Priority reflects user impact, not engineering effort.
    """


```

--------------------------------

### Test Task Failure Contracts with Pytest

Source: https://docs.shepherd-agents.ai/guides/test-shepherd-code

Test Shepherd's typed failures, such as tasks requiring a docstring or tasks called outside a workspace.

```python
import pytest


def test_bodyless_task_requires_docstring():
    with pytest.raises(TypeError, match="docstring or guidance"):

        @sp.task
        def nameless(x: str) -> str:  # no docstring -> rejected at definition
            pass


def test_task_outside_workspace_refuses():
    with pytest.raises(RuntimeError):
        triage_change(SAMPLE_DIFF)  # no workspace open -> no default model

```

--------------------------------

### Define Triage Dataclass

Source: https://docs.shepherd-agents.ai/tutorials/first-shepherd-app

Define the contract for the Triage task using a frozen dataclass. This specifies the expected fields and their types for the model's output.

```python
from dataclasses import dataclass

import shepherd as sp


@dataclass(frozen=True)
class Triage:
    category: str   # bugfix | feature | docs | refactor
    priority: str   # low | medium | high
    rationale: str
```
Tokens:
Raw