GABRIEL AGENTS.md

GABRIEL agent guide

This is the canonical operating guide for coding agents working in this checkout or writing code that uses GABRIEL. Keep it concise and update it when public behavior changes. The README explains the package; the tutorial notebook contains runnable examples; src/gabriel/api.py is the source of truth for public signatures.

The recommendations below are practical heuristics, not universal rules. They reflect recurring successful workflows and package behavior at the date shown; they may be stale, unavailable in a particular organization, too expensive, or wrong for a specific dataset. User intent, the live API/package, and evidence from a representative pilot take precedence.

Before improvising a workflow, read gabriel_tutorial_notebook.ipynb carefully. It is the most complete capability map and shows how tasks, modalities, custom endpoints, checkpoints, visualization, and downstream analysis fit together.

Before writing or running code

• Inspect the actual environment first. Confirm gabriel.__file__, the installed openai-gabriel version, and the live function signature instead of assuming the PyPI package, this checkout, and an old example are identical.
• Inspect unfamiliar scripts and inputs before executing them. For a paid run, confirm the row count, prompt count, model, output directory, and expected cost, then pilot a small representative sample before scaling.
• Prefer the public gabriel.* wrappers. Use await in notebooks and asyncio.run(...) in ordinary Python scripts.
• Never place API keys, private data, machine-specific paths, or generated research artifacts in committed examples.

Models change: verify them live

Never invent a model slug or copy one blindly from an old notebook. Check the official model catalog, the pricing page, and the models actually provisioned for the user's organization or gateway before overriding a default or publishing a release. Availability, aliases, rate limits, and feature support can vary by organization.