GEAR MODELS — AGENT INSTRUCTIONS
================================

You are using the Gear Models platform: a fal.ai-compatible API for self-hosted
3D, segmentation, and geometry models. It is a drop-in replacement for the
`fal_client` Python SDK. Self-hosted models run on Gear's own H200 GPUs; every
other model id is forwarded to official fal.ai. The user holds a single
credential, GEAR_KEY.

1. INSTALL
   Install the client (it pulls the official `fal-client` from PyPI):

     pip install gear-client --extra-index-url https://models.alayalab.ai/install/simple/

2. CREDENTIAL
   The user provides one secret. Export it before running:

     export GEAR_KEY=<the user's gear key>

   Do not hardcode the key in source. Read it from the environment.

3. USAGE
   The ONLY change from stock fal.ai code is the import line:

     import gear_client as fal_client

   Everything else is the standard fal_client API: submit / status / result /
   subscribe / cancel, and file uploads.

   Submit-and-wait example (image -> 3D mesh):

     import gear_client as fal_client

     handler = fal_client.submit("gear/pixal3d", arguments={"input": {
         "image_url": "https://example.com/chair.png",
     }})
     result = fal_client.result("gear/pixal3d", handler.request_id)
     print(result["mesh"]["url"])   # a ready-to-download GLB URL

   Or subscribe (blocks until done, polling under the hood):

     result = fal_client.subscribe("gear/pixal3d", arguments={"input": {
         "image_url": "https://example.com/chair.png",
     }})

   SAM3 image segmentation example:

     result = fal_client.subscribe("gear/sam3", arguments={"input": {
         "image_url": "https://raw.githubusercontent.com/opencv/opencv/master/samples/data/messi5.jpg",
         "prompt": "person",
     }})
     print(result["detections"]["url"], result["mask"]["url"])

   MoGe-2 monocular geometry example:

     result = fal_client.subscribe("gear/moge2", arguments={"input": {
         "image_url": "https://example.com/room.png",
         "include_glb": True,
         "include_raw_maps": True,
     }})
     print(result["depth"]["url"], result.get("glb", {}).get("url"))

4. MODELS
   Current primary self-hosted models on Gear H200 (use the gear/ namespace):
     gear/pixal3d        - image -> high-fidelity textured 3D mesh (Pixal3D)
     gear/sam3           - image + text prompt -> segmentation masks (SAM3)
     gear/moge2          - image -> depth/normal/point maps and optional GLB/PLY (MoGe-2)

   Other self-hosted registry entries can be discovered with GET /models and may
   include:
     gear/trellis2       - image -> 3D asset (TRELLIS.2)
     gear/motionbricks   - motion prompt -> animation outputs (MotionBricks)
     gear/sam3d-objects  - image + mask -> Gaussian splat object (SAM 3D Objects)
   Their results are returned as ready-to-download URLs (GLB, and where
   applicable additional formats).

   Any other model id (e.g. fal-ai/flux/schnell) is auto-routed to official
   fal.ai through the same code path — the full fal model catalog works
   unchanged.

5. NOTES
   - Inputs accept fal-style `image_url` (a public URL) or a file uploaded via
     fal_client's upload helpers.
   - Outputs are URLs; download them with a normal HTTP GET.
   - Generation on the self-hosted 3D models can take a few minutes, and the
     first request after idle may pay a one-time cold start while a GPU spins
     up. Use result()/subscribe() which wait for completion.
   - You do NOT need access to any private repository. The Gear Key is all the
     user needs.

Endpoint: https://models.alayalab.ai