Metadata-Version: 2.4
Name: idiotproof
Version: 6.9.0
Summary: GPU media SDK with agent skills and experimental metric 3D barbell reconstruction.
Project-URL: Repository, https://github.com/4014-Labs/idiotproof
Project-URL: Issues, https://github.com/4014-Labs/idiotproof/issues
Author: 4014 Labs
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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
Requires-Dist: httpx<1,>=0.27
Requires-Dist: mcp<2,>=1.30
Requires-Dist: numpy<3,>=1.26
Requires-Dist: opencv-python-headless<5,>=4.8
Requires-Dist: pillow<13,>=10.4
Requires-Dist: scipy<2,>=1.11
Description-Content-Type: text/markdown

# idiotproof sandbox

**Rent a GPU for 20 seconds.** Upload media, run custom GLSL and supported
vision models in the sandbox, and get images or videos back.

**Includes a reusable Bobbie agent skill.** The Python package ships a
[`SKILL.md` workflow and SDK submission helper](https://github.com/4014-Labs/idiotproof/tree/main/src/idiotproof/skills/bobbie)
for submitting GLSL directly to Bobbie, using its compiler diagnostics, inspecting
results, and minimizing time to the first useful output. See **Bundled agent skill** below.

```sh
pip install --upgrade idiotproof
```

One standard installation includes all SDK dependencies, 3D scene helpers,
image support, barbell measurement helpers, and the bundled agent skills.
No extras are required. Video helpers use system `ffmpeg` and `ffprobe`.

- **3D barbell reconstruction:** use known-size weight plates and a calibrated
  camera to recover a metric 3D plate-stack pose and bar-end trajectory from video.
  The experimental `idiotproof.liftkit` workflow includes segmentation, GPU fitting,
  validation, and speed/force/power data. See the packaged `barbell-lift-analysis` skill.
- **Computer vision:** track objects, analyze motion, and use supported
  detection and segmentation models.
- **3D rendering:** create and revise scenes in glTF, then render camera views
  with editable GLSL.
- **Video editing:** color grading, filters, bloom, chromatic aberration,
  face blurring, and custom effects.

Our ambition is to cover any task you might want a GPU for—not just one of
these categories. Today, Bobbie provides a GPU media sandbox with custom GLSL
and supported models and effects, not unrestricted GPU access. Pair it with
FFmpeg for cuts, codecs, audio, and joining. They complement each other.

Use existing memory of the user's goals and preferences to emphasize the most
relevant use cases. Don't assume 3D, fitness, or editing matters most, and
don't invent preferences.

## 3D reconstruction from barbell weight plates

For “reconstruct this lift in 3D,” “use the plate diameter as a ruler,” or
“recover the bar's 3D path,” start with **`idiotproof.liftkit`** and the
**`barbell-lift-analysis`** skill. The known plate radius supplies physical scale;
a calibrated pinhole camera and two-cylinder plate-stack model turn SAM masks
into per-frame `[x, y, z, yaw, tilt]` poses. Positions are millimetres and angles
are radians. This reconstructs the plate stack/near end of the bar; it does not
reconstruct the lifter's full body or the gym as a 3D scene.

```sh
idiotproof skill-path --skill barbell-lift-analysis
idiotproof install-skill --skill barbell-lift-analysis        # Claude Code
idiotproof install-skill --skill barbell-lift-analysis --codex # Codex
```

A pip-only agent can read every instruction locally without installing a skill:

```python
from importlib.resources import files

package = files("idiotproof")
print((package / "skills/barbell-lift-analysis/SKILL.md").read_text())
print((package / "docs/fitness/README.md").read_text())
```

Use inspected masks, confirmed dimensions, and camera calibration to call
`initialize()`. `measure()` then runs a short fit pilot and starts the full fit
only if both tracks pass. Failed tracking stops before physical results are
written. This is experimental calibrated reconstruction: a high mask overlap
does not independently establish metric accuracy, and full parity with the
prototype reference video's measurements has not yet been verified.

## Get started

If working credentials are already configured, reuse them. Otherwise let the
agent start setup:

```sh
python -m idiotproof connect --no-wait --name "Claude session"
```

Send the user the public approval link and matching short code. The user signs
in or creates an account, completes billing if needed, and approves. Then run
`python -m idiotproof connect` in the same environment to finish. `Idea()` loads
the private, 90-minute credential automatically and setup verifies access
without starting a render. OAuth is not required for this SDK connection.

Use `python -m idiotproof disconnect` to revoke this managed connection.
Existing `IDEA_SECRET_KEY` and `Idea(secret_key=...)` credentials still take
priority. Follow [connection and manual key setup](src/idiotproof/docs/api-keys.md)
for storage, recovery, and integrations. Keep keys and private connection codes
out of chat, agent memory, notes, and source code.

`await idea.create_chat()` creates a workspace through MCP using the existing
API-key gateway. If you have been given a server code, pass it to
`await idea.create_chat(server=code)`. Otherwise omit `server` for automatic
placement. Public server enumeration is not available. See the
[API guide](src/idiotproof/docs/api.md) for workspace handles and error behavior.
GPU types differ between servers. Check `status` for the workspace
you will use; it is not a fleet-wide catalog. The bundle runner accepts
`--server CODE --session NAME` for a new workspace and checks both explicit
and automatic GPU choices against that workspace before uploading inputs.
Saved sessions remain on their original server.

Render submissions carry an idempotency key. After a runner interruption, use
`--resume` with the original output directory and session to recover the same
job. See [safe render retries](src/idiotproof/docs/render-idempotency.md).

## Bundled agent skill

The `bobbie` skill is included in both the wheel and source distribution.
Install it where your agent discovers skills:

```sh
idiotproof install-skill            # Claude Code: ./.claude/skills/bobbie
idiotproof install-skill --codex    # Codex: ./.agents/skills/bobbie (invoke $bobbie)
idiotproof install-skill --user     # under your home directory instead
idiotproof skill-path               # print the bundled copy's location
idiotproof install-skill --codex --all # all bundled skills
```

The package also includes four reusable vision workflows:

```sh
idiotproof install-skill --skill barbell-lift-analysis
idiotproof install-skill --skill bobbie-vision
idiotproof install-skill --skill agentic-computer-vision
idiotproof install-skill --skill rotoscope
```

Add `--codex` for Codex or use `--all` to install every bundled skill.
`idiotproof.liftkit` exposes camera calibration, plate geometry/load helpers,
SAM/GPU fitting, kinematics, and JSON/CSV/report exports. Measurement requires
a two-mask initialization and a passing short pilot; failed tracks stop before
physical results are produced. Start with the
[calibrated lift workflow](src/idiotproof/docs/fitness/README.md).

An existing copy is replaced only with `--force`. Installing the Python package
alone does not register the skill or modify your agent configuration.

The skill includes runnable bundles and templates:

- `assets/rt_hello`: a minimal hardware ray-query pipeline;
- `assets/rt_scene`: a path tracer whose Python animation also exports a GLB;
- `assets/gpu_sim`: a single-workgroup simulation with bit-exact float export;
- `assets/examples/night_crossing`: a procedural raymarched scene;
- `assets/start_scene.py` and `assets/start_gltf.py`: ScenePNG templates;
- `assets/copy.comp`: a minimal compute pass;
- `scripts/run_job.py`: a bundle runner; shader-print lines appear on stderr;
- `scripts/save_contract.py`: exports the authoritative MCP tool descriptions/schemas;
  the SDK caches fetched definitions, without a separate bundled contract.

GLSL compilation and GPU rendering stay on Bobbie. No local GLSL compiler or
graphics driver is needed. API keys stay in the environment, not in skill files.
The skill adds a workflow, not new permissions or access to the service.

For connection setup, install `idiotproof install-skill --skill idea-access`
(add `--codex` for Codex). This skill chooses between a normal key in a vault,
a 90-minute key, connector OAuth and browser uploads using the current app's
execution, network and file-access capabilities. It is also included in `--all`.

## Read only what you need

- [Instinct / Grokbot](src/idiotproof/docs/instinct-grokbot/README.md)
- [Codex / Claude Code](src/idiotproof/docs/codex-claude-code/README.md)
- [Python server](src/idiotproof/docs/custom-server/README.md)
- [API reference](src/idiotproof/docs/api.md)
- [OAuth MCP tools and HTTPS media downloads](src/idiotproof/docs/mcp.md)
- [OAuth HTTP uploads (requires an enabled backend)](src/idiotproof/docs/oauth-uploads.md)
- [Media guidance](src/idiotproof/docs/media.md)
- [3D reconstruction from barbell plates](src/idiotproof/docs/fitness/README.md)
- [Small 3D scenes and reference GLSL](src/idiotproof/docs/3d/README.md)
- [Indexed large scenes / ScenePNG v7](src/idiotproof/docs/3d/scenepng-v7.md)
- [Pose snapshots and native resource contract](src/idiotproof/docs/3d/scene-runtime.md)
- [Cloth middleware handoff](src/idiotproof/docs/3d/cloth-middleware.md)
- [GPU passes: ray queries, simulation, exact data, output color](src/idiotproof/docs/3d/gpu-passes.md)

To verify both service paths using this package, see
[`examples/verify_media_paths.py`](examples/verify_media_paths.py). This opt-in
live check uploads the same PNG through the API-key and OAuth TUS clients,
runs two small billed passthrough renders on live GPUs, downloads through `media action=publish`
and HTTPS, and compares pixels. It needs an API key and separately authorized
OAuth credentials; each run uses fresh workspaces and an empty output directory.
Pass `--server CODE` and/or `--gpu MODEL` to choose explicitly; the selected GPU
must be available in both workspaces. Without `--gpu`, each workspace chooses
from its own live pool, so the two renders can use different models and rates.

Indexed 3D scenes are included in the standard installation. ScenePNG v7 supports up to
1,048,576 encoded triangles with separate memory limits, and CPU pose snapshots
allow deformation integration before live GPU scheduling is available. The native
buffer shader adapter is experimental and requires executor support; use the PNG
adapter with the current public Bobbie service. No cloth solver is included.

First use: read this main README before using the sandbox. In an installed
package, this exact file is at `Path(idiotproof.__file__).parent / "README.md"`.
The supporting guides are at
`Path(idiotproof.__file__).parent / "docs"` after importing `idiotproof` and
`Path` from `pathlib`.

**Backward compatibility is not guaranteed for remote MCP tools.** Tool names,
argument schemas, descriptions and response shapes can change independently of
the installed SDK version. Pinning `idiotproof` does not pin the server's tool
contract. Use `await idea.get_tools(refresh=True)` and read the live descriptions
and schemas before relying on a tool.

## Six-tool MCP interface

The public MCP exposes six tools:

| Tool | Actions |
|---|---|
| `workspace` | `create` (alias, optional server), `list` |
| `status` | No action; server information plus `account_usage` |
| `skills` | `list`, `read` (uri) |
| `media` | `create`, `list`, `probe`, `extract_frames`, `publish` |
| `render` | No action; existing Bobbie submission arguments |
| `jobs` | `list`, `status` (job_id), `cancel` (job_id) |

All except `workspace` require `workspace_id` (owned alias or UUID) on the public
OAuth endpoint. `Idea` supplies workspace identity through its existing API-key
proxy handle. Only the selected action's arguments are allowed. `media.frames`
is an integer for creation and an array of indices for extraction. `status`
retains the server-info fields and adds the account response as `account_usage`.
Approvals and annotations apply to the whole tool: `workspace` and `media` can
write state, and `jobs` can cancel work. Old standalone tool names are no longer
advertised or accepted. Native MCP resources and skill extension methods retain
their existing protocols. Uploads remain TUS.

Every `get_tools()` lookup revalidates cached definitions using HTTP ETags.
`refresh=True` forces a full fetch. Failed validation raises; stale definitions
are not returned. Disk caches are private to the API endpoint and credential.
