Metadata-Version: 2.4
Name: idiotproof
Version: 7.0.13
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: pyyaml<7,>=6
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.
- **Barbell equipment catalogue:** `idiotproof.catalogue`, 216 sourced items (bars, plates,
  collars, materials, floors, air drag), every number graded with its uncertainty and source.
- **Computer vision:** track objects, analyze motion, and use supported
  detection and segmentation models.
- **3D rendering:** load glTF/GLB (animation included) or build scenes in code,
  pack them as ScenePNG 8 textures (`idiotproof.scenepng`) and ray-trace them on Bobbie.
- **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.

## Helpers are starting points

This is the core design of every helper and skill in idiotproof. The helpers are
**memoized scripts**, not a framework. Agents are smart: give them a good starting
point and they can recover from the rest. Each helper is code that already meets our
standards for speed and quality, so an agent doesn't have to re-derive it.

- **Usefulness over reliability.** Helpers cover the common path and stay short enough
  to read in one sitting. Handling the unusual case belongs to the agent running the job
  (and to the backend service it calls), not to more code here.
- **Read, copy, change.** Don't treat a helper as a black box. Find its source,
  copy what you need into your project, and change it for your job:

  ```sh
  python -c "import idiotproof, pathlib; print(pathlib.Path(idiotproof.__file__).parent)"
  idiotproof skill-path --skill rotoscope          # a skill's directory
  ```

  In a copied module, replace relative imports (`from . import stream`) with absolute
  ones (`from idiotproof.roto import stream`).
- **Send the diff back.** Keep `diff -u <installed file> <your copy> > change.patch`.
  Improvements return to this repo with `git apply`, so the next agent starts from them.
- **Memoize what you rewrite.** A script you or another agent has written twice for
  the same kind of job belongs here as a helper.
- **Use this repo as inspiration, not just a library.** You will see the biggest gains
  from helpers built for your exact use case. `idiotproof.catalogue` is an example of
  extreme optimization for one domain: every common barbell, plate, collar, material and
  floor, with dimensions, grades, uncertainty and sources. We encourage you to
  mass-categorize the data of whatever domain you care about the same way.

## Barbell tracking and lift analysis

For “track barbells,” plate masks or squat/bench/deadlift reconstruction, use the
packaged **barbell-lift-analysis** skill and `idiotproof barbell` helpers. The
seven-step workflow identifies equipment and focal length, adapts GLSL
constraints, visually reviews masks, smooths numeric states on CPU, shows
occlusion-aware CPU wireframes for user approval, then analyzes and remembers
the lift. Keep SAM prompts simple; diagnose bad masks before a targeted retry.
The default target is one plate stack at the camera-nearest end. Its SAM mask,
GLSL fit and CPU wireframe share that scope. Only selected plate geometry is
evaluated; pose is local to the stack's inner face. Whole-bar COM/force requires
a separate explicit reconstruction model.

```sh
idiotproof skill-path --skill barbell-lift-analysis
idiotproof install-skill --skill barbell-lift-analysis --codex
idiotproof barbell --help
idiotproof barbell prepare lift.mp4 session
# Inspect source and add the nearest stack's box/point to recipe.json.
idiotproof barbell build session/recipe.json session/chunk-000
```

An agent can read all instructions directly from the pip package:

```python
from importlib.resources import files
print((files("idiotproof") / "skills/barbell-lift-analysis/SKILL.md").read_text())
```

The editable starter has JSON equipment/camera/candidate configuration and
separate generated GLSL. Build locally, submit through the existing Bobbie runner,
inspect the first returned chunk before scheduling more, and preserve complete
numeric `PRO_FIT` text separately from mask-preview video. One fused job can
return both. Physical assumptions and camera focal units stay explicit.

This experimental replacement is modular: `liftkit.constraints` holds the
adaptable model, `tracking` builds/collects chunks, and `trajectory` handles CPU
smoothing/rendering and approved analysis. The old two-mask `initialize/measure`
API remains a legacy migration path; it is no longer the skill's default.
Video helpers need FFmpeg on PATH. Narrow GPU correctness/performance evidence
exists; general real-video 3D accuracy and full CPU/GPU search-state parity remain
open. See [workflow details](src/idiotproof/docs/fitness/README.md).

## 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. The replacement workflow reviews masks and asks for wireframe approval before
physical interpretation. 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 8 templates (meshes in code; your glTF/GLB);
- `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)
- [3D scenes on Bobbie (ScenePNG 8)](src/idiotproof/docs/3d/README.md)
- [Render helpers: film / preview / film3d, preflight, splitting, stitching](src/idiotproof/render/README.md)
- [ScenePNG 8: use, format, migrating from v6/v7](src/idiotproof/docs/3d/scenepng-8/README.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.

3D scenes are included in the standard installation as ScenePNG 8
(`idiotproof.scenepng`). It has no format triangle cap: the queue's geometry budget
decides, and `fit_geometry` lowers far detail to fit. glTF node, morph and skin
animation is baked into vertex frames. The v7 names (`prepare_scene`, ...) still
import from `idiotproof` and run on ScenePNG 8; `gltf_to_png` (v6) is retired.

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.
