### 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 # the ordered record of every boundary crossing shepherd run changeset # 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 ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.