agenthand 0.1.0__tar.gz

agenthand-0.1.0/.env.example

@@ -0,0 +1,16 @@
+# agenthand environment - copy to .env and fill in locally.
+# Placeholder NAMES only. Never commit a real .env file.
+
+# Meta Model API key (server-side only; a dedicated judge key is used for
+# judged traffic - never put either in source control)
+META_API_KEY=
+
+# Local data directory: asset store + JSONL cost ledger live here.
+# Defaults to ./data under the project root when unset.
+AGENTHAND_DATA_DIR=
+
+# Fail-closed total spend cap in USD across ALL billable model calls.
+# Calls refuse before they run if they would push the ledger past this.
+# Default when unset: 120.00 working cap. This variable may only LOWER
+# the cap; values above the 150.00 hard ceiling are clamped to it.
+AGENTHAND_TOTAL_SPEND_CAP_USD=120.00

agenthand-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# Secrets - never commit real credentials
+.env
+.env.*
+!.env.example
+*.key
+*.pem
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.pytest_cache/
+
+# agenthand runtime data (asset store + cost ledger live here)
+data/
+
+# OS noise
+.DS_Store

agenthand-0.1.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to agenthand are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/), and the project uses
+semantic versioning.
+
+## [0.1.0] - 2026-10-27
+
+First public release. agenthand is an MCP server (stdio transport) that
+gives AI agents three tools for turning a seller's messy product photos
+into listing-ready material. The seller never opens it; their agent
+calls it.
+
+### Added
+
+- `identify` — reads a photo and plans the listing shot: a structured
+  description of the item, the cut-out concept with alternates, a
+  suggested title, listing bullets, and condition notes.
+- `cut_out` — cuts the product out of its photo and returns a
+  transparent PNG behind an `asset://` handle. The mask is
+  quality-checked, with one bounded retry on a poor mask, and the
+  result includes a mask review (bounding box, fill, frame-edge
+  contact, warnings).
+- `draw` (Fidelity Lock) — stages the real product into a generated
+  scene without regenerating the product. The stored foreground is
+  composited untouched onto a generated background plate, and the
+  result ships with a fidelity receipt: hashes for the source photo,
+  the foreground, and the mask, plus the changed-pixel count measured
+  on the delivered file. The receipt also states what the count
+  excluded.
+- `agenthand-verify` — a standalone checker that re-derives a fidelity
+  receipt from the files on disk, and can verify an exported
+  source/final/mask triple with no server involved. It passes only on
+  exactly zero changed pixels with real coverage.
+- One billing choke point for every model call: reserve-then-settle
+  accounting against a local ledger, a fail-closed spend cap, and a
+  cost receipt per call. A response with no usable usage settles at
+  its reserved projection rather than $0, and an unpriced model raises
+  instead of estimating.
+- Ingest by asset handle, http(s) URL, or base64 data URI, with size
+  caps, EXIF orientation applied, and HEIC support. Colour profiles
+  are preserved end to end and recorded on the receipt.
+- Images chain between tools as `asset://` handles instead of bytes,
+  and every asset is readable by the client as an MCP resource at its
+  own URI.

agenthand-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.5
+Name: agenthand
+Version: 0.1.0
+Summary: agenthand: an MCP server that gives AI sales agents three production tools - identify, cut_out, draw - for turning messy product photos into listing-ready images.
+Author: Daniel Wagner
+License: Proprietary
+Requires-Python: >=3.12
+Requires-Dist: mcp<3,>=2.0
+Requires-Dist: meta-sam-parser<0.2,>=0.1.0
+Requires-Dist: numpy<3,>=1.26
+Requires-Dist: openai<4,>=1.66
+Requires-Dist: opencv-python-headless<6,>=4.8
+Requires-Dist: pillow-heif<2,>=1.8
+Requires-Dist: pillow<14,>=10
+Provides-Extra: dev
+Requires-Dist: hypothesis<7,>=6; extra == 'dev'
+Requires-Dist: pytest<10,>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agenthand
+
+<p align="center">
+  <img src="assets/logo-rotating-v2.gif" alt="agenthand logo: a robot hand presenting three rotating arcs, framed by registration brackets" width="420">
+</p>
+
+An MCP server for AI agents that help people sell things.
+
+The seller never opens agenthand. Their agent calls it. A seller hands their
+agent a messy product photo; agenthand turns it into listing-ready material
+through three tools, in the order a listing is produced:
+
+| Tool | What it does |
+|---|---|
+| `draw` | Places the real product, pixel-untouched, into a generated scene (a chair in a regal room, a game lot on a clean table) and returns the composite with a fidelity receipt. |
+| `cut_out` | Segments the product out of its photo and returns a transparent PNG, referenced by an asset handle. The concept is optional; without one, the planning step runs internally. |
+| `identify` | The planning step inside the chain: reads a photo and plans the cut, returning a structured description plus the segmentation-ready noun-phrase concept (with alternates) that `cut_out` consumes. |
+
+## Fidelity Lock
+
+`draw` never regenerates the product. The invariant, enforced in code:
+
+1. Segmentation extracts the real product foreground and its mask.
+2. The product layer is stored untouched, with hashes recorded for the
+   source, the foreground, and the mask: both the file-byte hash and the
+   decoded-pixel hash of each.
+3. The image model generates ONLY the background scene plate. Its
+   interface takes a prompt and dimensions, never product pixels.
+4. Deterministic code composites the original product layer onto that
+   plate. The plate is resized and cropped to the product's dimensions;
+   the product layer is never scaled.
+5. `draw` refuses anything that is not a `foreground_png` asset chained
+   back to a source photo, and verifies the stored hashes before a single
+   pixel moves.
+6. The result ships with a fidelity receipt: source, foreground, and mask
+   hashes, the delivered file's own hashes, the transformations applied,
+   the measured count of changed opaque foreground pixels, the model
+   calls made, and their cost. The receipt also publishes what the count
+   excluded: the edge-band pixel count and its maximum width, the opaque
+   share of the mask, the exact changed-pixel predicate with tolerance 0,
+   and the colour-profile identity of the source photo and the composite
+   (a dropped or changed ICC profile recolours the product while pixel
+   values stay identical, so it is recorded and counted as a fidelity
+   failure).
+
+The claim is precise: the stored extracted foreground reached the
+composite unchanged, and its hashes pin exactly which layer that was.
+Edge-band pixels (partially transparent) blend with the plate during
+compositing; the receipt counts them separately instead of overclaiming.
+The receipt's counts are measured on the delivered file, decoded back
+from the store, and can be re-derived independently:
+`composite.verify_receipt_from_disk` recounts from the stored files,
+checks the receipt's own hashes against the assets it names, and
+passes only on exactly zero changed pixels with real coverage; the
+standalone `agenthand-verify SOURCE FINAL MASK` checker verifies
+exported files with no store at all and likewise refuses a mask that
+selects nothing. Ingest accepts the
+formats phones produce, including HEIC, and preserves each photo's
+embedded colour profile end to end.
+
+A bounded mask-recovery loop guards `cut_out`: the mask is quality-checked,
+and on a poor mask the tool retries once with an alternate concept phrase
+from the planning step. Every attempt is traced in the receipt.
+
+## Asset handles
+
+Tools never pass image bytes back and forth. Every image is stored locally
+(with a per-asset sidecar record, written atomically) and referenced as
+`asset://<id>`. Handles chain between tools: `identify` reads one,
+`cut_out` returns a new one, `draw` consumes it.
+
+Photos get in through ingest: a tool's image argument may be an existing
+handle, an http(s) URL, or a base64 data URI. Ingest caps the byte and
+pixel size, applies EXIF orientation, and normalizes to 8-bit RGBA PNG.
+Images get out two ways: `draw` returns an image preview with its result,
+and every asset is readable by the client as the MCP resource at its own
+`asset://<id>` URI.
+
+## Cost receipts and the spend cap
+
+Every billable call flows through one choke point
+(`src/agenthand/meta_client.py`) using reserve-then-settle accounting:
+under a file lock, the projected worst-case cost is checked against the
+ledger and reserved as a pending receipt; after the call, a settlement
+receipt records the actual cost priced from the provider's usage counts.
+If a call fails after it may have billed, the reservation stays counted.
+A call whose provider response carries no usable usage settles at its
+reserved projection rather than $0: missing usage never erases spend.
+Receipts land in a local JSONL ledger with tool, model, token and image
+counts, USD estimate, and the pricing-table version used. Prices live in
+one module (`src/agenthand/pricing.py`) so a price change is a one-line
+edit with a version bump; an unpriced model raises rather than estimating
+as $0. Every spend path shares the one ledger — the dry-run gate
+included (its asset store is isolated in a temp dir, its ledger is not).
+
+The server is fail-closed on spend. The working cap defaults to
+**$120.00**; configuration may move it up or down but never past the
+hard ceiling of **$150.00** (the hackathon credit amount), which no
+configuration can exceed. Corrupt, negative, or non-finite ledger
+entries refuse all spend: unknown spend state means no spend.
+
+## Status
+
+Hackathon build (Meta Global AI Developer Hackathon, Oct 26 - Nov 4,
+2026). All three tools are wired to the real Meta Model API through the
+spend-cap billing choke point — `identify` to muse-spark-1.3, `cut_out`
+to sam-3.1, `draw` to muse-image-1.0 — and the full chain has run live
+end to end. The verified run of 2026-10-26 (identify $0.007544,
+cut_out $0.0025, draw $0.01; 580,613 opaque pixels checked, 0 changed)
+is published with its fidelity receipt on the
+[project site](https://ausernameforyou.github.io/agenthand/#fidelity),
+where the same check can be re-run in the browser against the run's own
+files. The placeholder plate survives only behind an explicit dev flag
+for offline tests. Today the server runs locally over stdio; a hosted
+endpoint comes later.
+
+The server also exists as a single-binary Rust build (source in the
+`agenthand-rust` repository). It passed a parity gate against the frozen
+files of the verified run above, reproducing the run's counts and its
+output pixel hash, and a live run from the Rust binary was cross-checked
+by the Python verifier. The Python implementation remains the
+reference; the Rust build is a second implementation of the same
+server, and the two agree.
+
+## Run it
+
+Register agenthand with any MCP client. The primary route uses
+[uv](https://docs.astral.sh/uv/): nothing to install ahead of time, uv
+fetches the published package and runs it.
+
+```json
+{
+  "mcpServers": {
+    "agenthand": {
+      "command": "uvx",
+      "args": ["agenthand"],
+      "env": { "META_API_KEY": "…" }
+    }
+  }
+}
+```
+
+Or install the package with pip and point the client at the installed
+command:
+
+```bash
+pip install agenthand
+```
+
+```json
+{
+  "mcpServers": {
+    "agenthand": {
+      "command": "agenthand",
+      "env": { "META_API_KEY": "…" }
+    }
+  }
+}
+```
+
+The server starts and lists its tools without a key; the key is only
+needed when a tool makes a model call. Configuration is by environment
+variable; see `.env.example`.
+
+### From source (dev)
+
+```bash
+git clone https://github.com/AUsernameForYou/agenthand
+cd agenthand
+python3.12 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/agenthand          # stdio transport
+.venv/bin/pytest             # unit tests
+```

agenthand-0.1.0/README.md

@@ -0,0 +1,174 @@
+# agenthand
+
+<p align="center">
+  <img src="assets/logo-rotating-v2.gif" alt="agenthand logo: a robot hand presenting three rotating arcs, framed by registration brackets" width="420">
+</p>
+
+An MCP server for AI agents that help people sell things.
+
+The seller never opens agenthand. Their agent calls it. A seller hands their
+agent a messy product photo; agenthand turns it into listing-ready material
+through three tools, in the order a listing is produced:
+
+| Tool | What it does |
+|---|---|
+| `draw` | Places the real product, pixel-untouched, into a generated scene (a chair in a regal room, a game lot on a clean table) and returns the composite with a fidelity receipt. |
+| `cut_out` | Segments the product out of its photo and returns a transparent PNG, referenced by an asset handle. The concept is optional; without one, the planning step runs internally. |
+| `identify` | The planning step inside the chain: reads a photo and plans the cut, returning a structured description plus the segmentation-ready noun-phrase concept (with alternates) that `cut_out` consumes. |
+
+## Fidelity Lock
+
+`draw` never regenerates the product. The invariant, enforced in code:
+
+1. Segmentation extracts the real product foreground and its mask.
+2. The product layer is stored untouched, with hashes recorded for the
+   source, the foreground, and the mask: both the file-byte hash and the
+   decoded-pixel hash of each.
+3. The image model generates ONLY the background scene plate. Its
+   interface takes a prompt and dimensions, never product pixels.
+4. Deterministic code composites the original product layer onto that
+   plate. The plate is resized and cropped to the product's dimensions;
+   the product layer is never scaled.
+5. `draw` refuses anything that is not a `foreground_png` asset chained
+   back to a source photo, and verifies the stored hashes before a single
+   pixel moves.
+6. The result ships with a fidelity receipt: source, foreground, and mask
+   hashes, the delivered file's own hashes, the transformations applied,
+   the measured count of changed opaque foreground pixels, the model
+   calls made, and their cost. The receipt also publishes what the count
+   excluded: the edge-band pixel count and its maximum width, the opaque
+   share of the mask, the exact changed-pixel predicate with tolerance 0,
+   and the colour-profile identity of the source photo and the composite
+   (a dropped or changed ICC profile recolours the product while pixel
+   values stay identical, so it is recorded and counted as a fidelity
+   failure).
+
+The claim is precise: the stored extracted foreground reached the
+composite unchanged, and its hashes pin exactly which layer that was.
+Edge-band pixels (partially transparent) blend with the plate during
+compositing; the receipt counts them separately instead of overclaiming.
+The receipt's counts are measured on the delivered file, decoded back
+from the store, and can be re-derived independently:
+`composite.verify_receipt_from_disk` recounts from the stored files,
+checks the receipt's own hashes against the assets it names, and
+passes only on exactly zero changed pixels with real coverage; the
+standalone `agenthand-verify SOURCE FINAL MASK` checker verifies
+exported files with no store at all and likewise refuses a mask that
+selects nothing. Ingest accepts the
+formats phones produce, including HEIC, and preserves each photo's
+embedded colour profile end to end.
+
+A bounded mask-recovery loop guards `cut_out`: the mask is quality-checked,
+and on a poor mask the tool retries once with an alternate concept phrase
+from the planning step. Every attempt is traced in the receipt.
+
+## Asset handles
+
+Tools never pass image bytes back and forth. Every image is stored locally
+(with a per-asset sidecar record, written atomically) and referenced as
+`asset://<id>`. Handles chain between tools: `identify` reads one,
+`cut_out` returns a new one, `draw` consumes it.
+
+Photos get in through ingest: a tool's image argument may be an existing
+handle, an http(s) URL, or a base64 data URI. Ingest caps the byte and
+pixel size, applies EXIF orientation, and normalizes to 8-bit RGBA PNG.
+Images get out two ways: `draw` returns an image preview with its result,
+and every asset is readable by the client as the MCP resource at its own
+`asset://<id>` URI.
+
+## Cost receipts and the spend cap
+
+Every billable call flows through one choke point
+(`src/agenthand/meta_client.py`) using reserve-then-settle accounting:
+under a file lock, the projected worst-case cost is checked against the
+ledger and reserved as a pending receipt; after the call, a settlement
+receipt records the actual cost priced from the provider's usage counts.
+If a call fails after it may have billed, the reservation stays counted.
+A call whose provider response carries no usable usage settles at its
+reserved projection rather than $0: missing usage never erases spend.
+Receipts land in a local JSONL ledger with tool, model, token and image
+counts, USD estimate, and the pricing-table version used. Prices live in
+one module (`src/agenthand/pricing.py`) so a price change is a one-line
+edit with a version bump; an unpriced model raises rather than estimating
+as $0. Every spend path shares the one ledger — the dry-run gate
+included (its asset store is isolated in a temp dir, its ledger is not).
+
+The server is fail-closed on spend. The working cap defaults to
+**$120.00**; configuration may move it up or down but never past the
+hard ceiling of **$150.00** (the hackathon credit amount), which no
+configuration can exceed. Corrupt, negative, or non-finite ledger
+entries refuse all spend: unknown spend state means no spend.
+
+## Status
+
+Hackathon build (Meta Global AI Developer Hackathon, Oct 26 - Nov 4,
+2026). All three tools are wired to the real Meta Model API through the
+spend-cap billing choke point — `identify` to muse-spark-1.3, `cut_out`
+to sam-3.1, `draw` to muse-image-1.0 — and the full chain has run live
+end to end. The verified run of 2026-10-26 (identify $0.007544,
+cut_out $0.0025, draw $0.01; 580,613 opaque pixels checked, 0 changed)
+is published with its fidelity receipt on the
+[project site](https://ausernameforyou.github.io/agenthand/#fidelity),
+where the same check can be re-run in the browser against the run's own
+files. The placeholder plate survives only behind an explicit dev flag
+for offline tests. Today the server runs locally over stdio; a hosted
+endpoint comes later.
+
+The server also exists as a single-binary Rust build (source in the
+`agenthand-rust` repository). It passed a parity gate against the frozen
+files of the verified run above, reproducing the run's counts and its
+output pixel hash, and a live run from the Rust binary was cross-checked
+by the Python verifier. The Python implementation remains the
+reference; the Rust build is a second implementation of the same
+server, and the two agree.
+
+## Run it
+
+Register agenthand with any MCP client. The primary route uses
+[uv](https://docs.astral.sh/uv/): nothing to install ahead of time, uv
+fetches the published package and runs it.
+
+```json
+{
+  "mcpServers": {
+    "agenthand": {
+      "command": "uvx",
+      "args": ["agenthand"],
+      "env": { "META_API_KEY": "…" }
+    }
+  }
+}
+```
+
+Or install the package with pip and point the client at the installed
+command:
+
+```bash
+pip install agenthand
+```
+
+```json
+{
+  "mcpServers": {
+    "agenthand": {
+      "command": "agenthand",
+      "env": { "META_API_KEY": "…" }
+    }
+  }
+}
+```
+
+The server starts and lists its tools without a key; the key is only
+needed when a tool makes a model call. Configuration is by environment
+variable; see `.env.example`.
+
+### From source (dev)
+
+```bash
+git clone https://github.com/AUsernameForYou/agenthand
+cd agenthand
+python3.12 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/agenthand          # stdio transport
+.venv/bin/pytest             # unit tests
+```

agenthand-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agenthand"
+version = "0.1.0"
+description = "agenthand: an MCP server that gives AI sales agents three production tools - identify, cut_out, draw - for turning messy product photos into listing-ready images."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "Proprietary" }
+authors = [
+    { name = "Daniel Wagner" },
+]
+# Pinned as floor + next-major ceiling: the floor is the oldest
+# version the suite is verified against (or the first version with
+# an API we call), the ceiling keeps a future major release from
+# being installed untested. Verified set at pin time (2026-10-27):
+# mcp 2.3.0, openai 3.39.0, Pillow 13.0.0, pillow-heif 1.8.1,
+# meta-sam-parser 0.1.0, numpy 2.5.4, opencv-python-headless 5.0.0.93.
+dependencies = [
+    "mcp>=2.0,<3",
+    # Floor is the first release line with the Responses API
+    # (meta_client.segment_image calls client.responses.create).
+    "openai>=1.66,<4",
+    "Pillow>=10,<14",
+    "pillow-heif>=1.8,<2",
+    "meta-sam-parser>=0.1.0,<0.2",
+    # measure.py (prototype estimator): classical CV + array math.
+    # composite.py / segmentation.py use numpy + cv2 for the
+    # fidelity counting and mask analysis hot paths.
+    "numpy>=1.26,<3",
+    "opencv-python-headless>=4.8,<6",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8,<10",
+    # Property-based tests for the verifier/compositor counting
+    # core (tests/test_fidelity_properties.py).
+    "hypothesis>=6,<7",
+]
+
+[project.scripts]
+agenthand = "agenthand.server:main"
+agenthand-verify = "agenthand.verify:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agenthand"]
+
+# Keep the source distribution focused on installable source and release
+# metadata. The website images, test suite, and local build scripts are
+# development artifacts and would otherwise add roughly 14 MB to the sdist.
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "/.github",
+    "/assets",
+    "/docs",
+    "/scripts",
+    "/tests",
+    "/BUILD_LOG.md",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

agenthand-0.1.0/server.json

@@ -0,0 +1 @@
+{"$schema":"https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json","description":"Turn messy product photos into listing-ready images, with a fidelity receipt on every staged shot.","name":"io.github.AUsernameForYou/agenthand","packages":[{"environmentVariables":[{"description":"Meta Model API key. The server starts and lists its tools without one; the key is required when a tool makes a model call.","format":"string","isRequired":true,"isSecret":true,"name":"META_API_KEY"}],"identifier":"agenthand","registryBaseUrl":"https://pypi.org","registryType":"pypi","runtimeHint":"uvx","transport":{"type":"stdio"},"version":"0.1.0"}],"repository":{"source":"github","url":"https://github.com/AUsernameForYou/agenthand"},"title":"agenthand","version":"0.1.0"}

agenthand-0.1.0/src/agenthand/__init__.py

@@ -0,0 +1,8 @@
+"""agenthand: an MCP server giving AI sales agents identify / cut_out / draw.
+
+The seller never opens agenthand; their agent calls it. Tools exchange
+asset handles (asset://<id>) instead of image bytes, every call writes a
+cost receipt, and billable spend is fail-closed behind a hard cap.
+"""
+
+__version__ = "0.1.0"