Metadata-Version: 2.4
Name: agentsam-sdk
Version: 0.1.0
Summary: Stdlib-first Agent Sam repository/data CLI and local SAM client, with an optional Rich terminal UI.
Author-email: Sam Primeaux <sam@inneranimalmedia.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/SamPrimeaux/agentsam-sdk
Project-URL: Repository, https://github.com/SamPrimeaux/agentsam-sdk
Project-URL: Issues, https://github.com/SamPrimeaux/agentsam-sdk/issues
Project-URL: npm, https://www.npmjs.com/package/@inneranimalmedia/agentsam-sdk
Keywords: agentsam,sam,agents,sdk,repository,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: tui
Requires-Dist: rich>=13.7.0; extra == "tui"
Dynamic: license-file

# 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.

```bash
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:

```bash
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`](https://github.com/SamPrimeaux/agentsam-sdk/blob/main/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:

```python
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`](https://github.com/SamPrimeaux/agentsam-sdk/blob/main/packages/agentsam-hooks/README.md)
for composition, permission, and subprocess transport rules.

## Optional sibling packages (not part of stdlib core)

| Package | Path | Notes |
|---------|------|-------|
| `agentsam-site-scrape` | [`../packages/agentsam-site-scrape/`](https://github.com/SamPrimeaux/agentsam-sdk/blob/main/packages/agentsam-site-scrape/) | Optional/network (`requests`); crawl→R2. Dual-homed with IAM `tools/agentsam-site-scrape/`. Does **not** fold into `agentsam_sdk`. |


## Internal Rich renderer preview

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

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

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

```bash
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.
