agentsam-sdk 0.1.0__tar.gz

agentsam_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Inner Animal Media
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentsam_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+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.

agentsam_sdk-0.1.0/README.md

@@ -0,0 +1,78 @@
+# 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.

agentsam_sdk-0.1.0/agentsam_sdk/__init__.py

@@ -0,0 +1,13 @@
+"""agentsam_sdk — stdlib-only toolkit for inneranimalmedia D1/repo audits.
+
+Every tool follows the runtime.contract pattern: ToolInput in, ToolResult out,
+plus a receipt written to output_dir for audit trail. No hardcoded
+identity/repo/workspace/tenant values anywhere in this package — see
+runtime.contract.HARD_LAW_NOTE.
+"""
+
+__version__ = "0.1.0"
+
+# Public local SAM client. Remote ACP, MCP and app-specific authorities remain
+# separately scoped; their mere existence does not grant this client access.
+from .client import AgentSamClient, AsyncAgentSamClient, Choose, Check, Score, SamClientError

agentsam_sdk-0.1.0/agentsam_sdk/cli.py

@@ -0,0 +1,263 @@
+"""agentsam CLI -- stdlib argparse only (no click/typer dep, per project
+convention: Python tooling here is stdlib-only).
+
+  agentsam data d1-bloat --quick --format markdown --output-dir /tmp/d1-bloat
+  agentsam data agentsam-walk --prefix agentsam_ --output-dir /tmp/walk
+  agentsam repository inventory --repo-root .. --output-dir /tmp/scan --format json
+  agentsam repository inventory --repo-root .. --format json | jq '.data.totals'
+  agentsam repository scan-bloat --root src --min-kb 10 --top 30 --format json
+  agentsam repository inspect --repo-root . --json --dupes | jq '.duplicates'
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from agentsam_sdk.runtime.contract import ToolInput, ToolResult
+
+
+def _print_result(result: ToolResult, fmt: str) -> None:
+    if fmt == "json":
+        print(json.dumps(result.to_dict(), indent=2, default=str))
+    else:
+        status = "OK" if result.ok else "FAIL"
+        print(f"[{status}] {result.tool} ({result.mode}) — {result.summary}", file=sys.stderr)
+        if result.error:
+            print(f"  error: {result.error}", file=sys.stderr)
+        for a in result.artifacts:
+            print(f"  wrote: {a}", file=sys.stderr)
+        # When markdown artifacts were written, surface path; else dump summary data keys
+        if fmt == "markdown" and result.ok and result.data.get("categories"):
+            # stdout stays quiet when artifacts exist; callers use the .md file
+            if not result.artifacts:
+                from agentsam_sdk.repository.inventory import _markdown
+
+                sys.stdout.write(_markdown(result.data))
+        if fmt == "markdown" and result.ok and result.data.get("files") is not None:
+            from agentsam_sdk.repository.scan_bloat import human_table
+
+            sys.stdout.write(
+                human_table(
+                    result.data.get("files") or [],
+                    scanned=int(result.data.get("file_count") or 0),
+                    total_kb=float(result.data.get("total_kb") or 0),
+                    total_tokens=int(result.data.get("total_est_tokens") or 0),
+                )
+            )
+
+
+def _cmd_data_d1_bloat(args: argparse.Namespace) -> int:
+    from agentsam_sdk.data import d1_bloat
+
+    mode = "full" if args.full else "quick"
+    ti = ToolInput(
+        mode=mode,
+        params={
+            "db": args.db, "config": args.config, "repo_root": args.repo_root,
+            "prefix": args.prefix, "workers": args.workers, "top": args.top,
+        },
+        output_dir=args.output_dir,
+    )
+    result = d1_bloat.run(ti)
+    _print_result(result, args.format)
+    return 0 if result.ok else 1
+
+
+def _cmd_data_agentsam_walk(args: argparse.Namespace) -> int:
+    from agentsam_sdk.data import agentsam_walk
+
+    ti = ToolInput(
+        mode="default",
+        params={"db": args.db, "config": args.config, "repo_root": args.repo_root, "prefix": args.prefix},
+        output_dir=args.output_dir,
+    )
+    result = agentsam_walk.run(ti)
+    _print_result(result, args.format)
+    return 0 if result.ok else 1
+
+
+def _cmd_repository_inventory(args: argparse.Namespace) -> int:
+    from agentsam_sdk.repository import inventory
+
+    ti = ToolInput(
+        mode="read-only",
+        params={
+            "repo_root": args.repo_root,
+            "top": args.top,
+            "min_bytes": args.min_bytes,
+            "by_ext": args.by_ext,
+            "include_node_modules": args.include_node_modules,
+            "include_venvs": args.include_venvs,
+            "include_git": args.include_git,
+            "include_dist": args.include_dist,
+            "follow_symlinks": args.follow_symlinks,
+        },
+        output_dir=args.output_dir,
+    )
+    result = inventory.run(ti)
+    _print_result(result, args.format)
+    return 0 if result.ok else 1
+
+
+def _cmd_repository_scan_bloat(args: argparse.Namespace) -> int:
+    from agentsam_sdk.repository import scan_bloat
+
+    ti = ToolInput(
+        mode="read-only",
+        params={
+            "root": args.root,
+            "top": args.top,
+            "min_kb": args.min_kb,
+            "ext": args.ext,
+            "exclude": args.exclude,
+        },
+        output_dir=args.output_dir,
+    )
+    result = scan_bloat.run(ti)
+    # Agent capture: --json-envelope prints data payload only (legacy tools/scan_bloat.py)
+    if args.json_envelope:
+        print(json.dumps(result.data if result.ok else {"ok": False, "error": result.error}, indent=2))
+        return 0 if result.ok else 1
+    _print_result(result, args.format)
+    return 0 if result.ok else 1
+
+
+def _cmd_repository_inspect(args: argparse.Namespace) -> int:
+    from agentsam_sdk.repository import inspect as repo_inspect
+
+    argv: list[str] = []
+    if args.repo_root:
+        argv.extend(["--repo-root", args.repo_root])
+    want_text = bool(args.text) or args.format in ("text", "markdown")
+    want_json = bool(args.json) or args.format == "json" or not want_text
+    if want_json and not want_text:
+        argv.append("--json")
+    if want_text and not want_json:
+        argv.append("--text")
+    if want_text and want_json:
+        # Explicit both → JSON wins (machine default) unless only --text
+        argv.append("--json")
+    if args.dupes:
+        argv.append("--dupes")
+    if args.all:
+        argv.append("--all")
+    if args.since:
+        argv.extend(["--since", args.since])
+    if args.recent is not None:
+        argv.extend(["--recent", str(args.recent)])
+    if args.largest is not None:
+        argv.extend(["--largest", str(args.largest)])
+    if args.out:
+        argv.extend(["--out", args.out])
+    return repo_inspect.main_cli(argv)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(prog="agentsam", description="agentsam_sdk CLI")
+    sub = ap.add_subparsers(dest="group", required=True)
+
+
+    data = sub.add_parser("data", help="D1 data audits")
+    data_sub = data.add_subparsers(dest="cmd", required=True)
+
+    bloat = data_sub.add_parser(
+        "d1-bloat",
+        help="database-scoped D1 audit (--quick=counts, --full=text sizes)",
+    )
+    bloat.add_argument("--db", help="D1 database name (else AGENTSAM_D1_DB_NAME)")
+    bloat.add_argument("--config", help="wrangler config path (else AGENTSAM_WRANGLER_CONFIG)")
+    bloat.add_argument("--repo-root", help="repo root wrangler runs from")
+    bloat.add_argument("--quick", action="store_true", default=True,
+                       help="All tables: COUNT(*) only (default)")
+    bloat.add_argument("--full", action="store_true",
+                       help="All tables: row counts + text/JSON LENGTH estimates")
+    bloat.add_argument("--prefix", help="Only tables whose name starts with this prefix")
+    bloat.add_argument("--workers", type=int, default=6)
+    bloat.add_argument("--top", type=int, default=40)
+    bloat.add_argument("--output-dir")
+    bloat.add_argument("--format", choices=["json", "markdown"], default="markdown")
+    bloat.set_defaults(func=_cmd_data_d1_bloat)
+
+    walk = data_sub.add_parser("agentsam-walk", help="walk agentsam_* tables")
+    walk.add_argument("--db")
+    walk.add_argument("--config")
+    walk.add_argument("--repo-root")
+    walk.add_argument("--prefix", default="agentsam_")
+    walk.add_argument("--output-dir")
+    walk.add_argument("--format", choices=["json", "markdown"], default="markdown")
+    walk.set_defaults(func=_cmd_data_agentsam_walk)
+
+    repo = sub.add_parser("repository", help="repository-level audits")
+    repo_sub = repo.add_subparsers(dest="cmd", required=True)
+    inv = repo_sub.add_parser(
+        "inventory",
+        help="file counts + sizes by logical category (jq-friendly JSON)",
+    )
+    inv.add_argument("--repo-root", default=".")
+    inv.add_argument("--output-dir")
+    inv.add_argument("--format", choices=["json", "markdown"], default="json")
+    inv.add_argument("--top", type=int, default=20, help="N largest files (0 to omit)")
+    inv.add_argument("--min-bytes", type=int, default=0)
+    inv.add_argument(
+        "--by-ext",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Include by_extension_detail with byte rollups (default: on)",
+    )
+    inv.add_argument("--include-node-modules", action="store_true")
+    inv.add_argument("--include-venvs", action="store_true")
+    inv.add_argument("--include-git", action="store_true")
+    inv.add_argument("--include-dist", action="store_true")
+    inv.add_argument("--follow-symlinks", action="store_true")
+    inv.set_defaults(func=_cmd_repository_inventory)
+
+    sb = repo_sub.add_parser(
+        "scan-bloat",
+        help="largest runtime source files (KB/lines/est. tokens)",
+    )
+    sb.add_argument("--root", default=".", help="directory to scan (default: cwd)")
+    sb.add_argument("--top", type=int, default=30)
+    sb.add_argument("--min-kb", type=float, default=0)
+    sb.add_argument(
+        "--ext",
+        default=".js,.ts,.jsx,.tsx,.mjs,.cjs",
+        help="comma-separated extensions",
+    )
+    sb.add_argument("--exclude", default="", help="extra dir names to exclude")
+    sb.add_argument("--output-dir")
+    sb.add_argument("--format", choices=["json", "markdown"], default="markdown")
+    sb.add_argument(
+        "--json-envelope",
+        action="store_true",
+        help="print ToolResult.data JSON only (agent/terminal capture)",
+    )
+    sb.set_defaults(func=_cmd_repository_scan_bloat)
+
+    insp = repo_sub.add_parser(
+        "inspect",
+        help="file walk: sizes + dates (+ optional --dupes SHA-256 groups)",
+    )
+    insp.add_argument("--repo-root", default=None)
+    insp.add_argument("--format", choices=["json", "markdown", "text"], default="json")
+    insp.add_argument("--json", action="store_true")
+    insp.add_argument("--text", action="store_true")
+    insp.add_argument("--dupes", action="store_true")
+    insp.add_argument("--all", action="store_true")
+    insp.add_argument("--since", default=None)
+    insp.add_argument("--recent", type=int, default=50)
+    insp.add_argument("--largest", type=int, default=30)
+    insp.add_argument("--out", default=None)
+    insp.set_defaults(func=_cmd_repository_inspect)
+
+    return ap
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())