agentsam-sdk

agentsam-sdk (Python)

Core repository/data commands remain stdlib-only (dependencies = []). Rich is an optional renderer dependency used by the SDK's internal terminal preview lab; it is not exposed as an installed-user renderer command.

pip install agentsam-sdk            # stdlib-only core
pip install "agentsam-sdk[tui]"     # optional Rich terminal renderer
agentsam repository inventory --repo-root /path/to/repo --format json

Requires Python 3.10+. For development from a checkout: cd python && pip install -e . then python -m unittest discover -s tests -v.

AgentSamClient.invoke()

The repository, data, hooks and agentsam CLI tools run entirely in Python. The local SAM client (AgentSamClient) delegates to the Node SAM kernel, so it needs Node 20+ and the npm package in the project or a parent directory:

npm install @inneranimalmedia/agentsam-sdk

The bridge is found automatically from the working directory. It is read-only by design: write, D1, CMS and terminal operations are refused (sam_bridge_operation_not_allowed). Without the npm package, invoke() raises sam_bridge_not_installed.

Protocol: ../protocol/README.md.

Portable lifecycle hooks

agentsam_sdk.hooks implements the same agentsam.hook.v1 envelope as the JavaScript/TypeScript, Go, Rust, command, and HTTP adapters. It is stdlib-only:

from agentsam_sdk.hooks import HookRuntime

hooks = HookRuntime()
hooks.register("pre_tool_use", lambda envelope: {
    "permission_decision": "allow"
})
result = await hooks.dispatch("pre_tool_use", {
    "tool_name": "repository.snapshot", "tool_args": {}
})

See ../packages/agentsam-hooks/README.md for composition, permission, and subprocess transport rules.

Optional sibling packages (not part of stdlib core)

Internal Rich renderer preview

The npm SDK owns the public interactive experience. For renderer development only:

cd ..
npm run ui:preview -- tour
npm run ui:preview -- thinking

The Python module can also be invoked directly after installing the optional extra:

cd python
pip install -e '.[tui]'
PYTHONPATH=. python -m agentsam_sdk.tui --scene dashboard --check

agentsam_sdk.tui is presentation-only. It does not define tools, execution policy, or public CLI vocabulary.