Metadata-Version: 2.4
Name: gigaflow
Version: 0.5.0
Summary: GigaFlow CLI — connect LLM/agent traces (Arize Phoenix, Logfire, Braintrust, MLflow, W&B Weave, or OTLP) to GigaFlow and run Flow analysis
Author-email: "GigaFlow AI, Inc." <james@gigaflow.io>
License: Apache-2.0
Project-URL: Homepage, https://github.com/GigaFlow-AI-Incorporated/gigaflow-sdk
Project-URL: Documentation, https://docs.gigaflow.io/
Project-URL: Repository, https://github.com/GigaFlow-AI-Incorporated/gigaflow-sdk
Project-URL: Changelog, https://github.com/GigaFlow-AI-Incorporated/gigaflow-sdk/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/GigaFlow-AI-Incorporated/gigaflow-sdk/issues
Keywords: gigaflow,llm,agent,observability,tracing,evaluation,flow-analysis,arize,phoenix,logfire,braintrust,mlflow,weave,otlp,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Environment :: Console
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: ruff>=0.1.6; extra == "dev"
Requires-Dist: mypy>=1.7.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Dynamic: license-file

# gigaflow CLI

Command-line client for **GigaFlow** — connect your LLM/agent traces to a GigaFlow
backend and run **Flow analysis** on them (atomize each step, attribute information
flow between atoms, score groundedness/relevance/fulfilment, diagnose failures).

The CLI is a thin client: your traces live in an observability platform (Arize
Phoenix, Logfire, Braintrust, MLflow, W&B Weave) or are sent via OTLP; the backend
does the compute; this CLI drives ingest → compute → inspection.

📖 **Documentation:** <https://docs.gigaflow.io/>

---

## Install

```bash
pip install gigaflow
```

The CLI is standard-library only — nothing else to pull in.

## Sign in

Run `gigaflow login` — it signs you in with your waitlist email and stores your
credentials in `~/.gigaflow/config.json`, so you only do it once:

```bash
gigaflow login
```

`gigaflow setup` also signs you in automatically, so a fresh user can go straight
to setup — no API key or backend URL needed; the hosted service
(`https://api.gigaflow.io/api/v1`) is the default.

Flow compute additionally needs an **OpenAI key** (sent only by the `compute`
command):

```bash
export OPENAI_API_KEY=sk-...
```

*On the hosted service, Flow LLM calls currently run on GigaFlow's platform key;
per-customer key billing is on the roadmap.*

For repeatable or CI setups, see the [gigaflow.env reference](https://docs.gigaflow.io/gigaflow-env/).

**Developer / self-hosted overrides** (hosted users don't need these):

| Env var | Purpose |
|---|---|
| `GIGAFLOW_BACKEND_URL` | Point the CLI at a non-default backend. Same as `--backend`. |
| `GIGAFLOW_API_KEY` | Static bearer key, bypassing interactive login. Same as `--api-key`. |

**Resolution order** (first set wins):
- Backend URL: `--backend <url>` > `$GIGAFLOW_BACKEND_URL` > saved config > the hosted service (`https://api.gigaflow.io/api/v1`)
- API key: `--api-key <key>` > `$GIGAFLOW_API_KEY` > saved config > none

---

## Try it in one command

Already have an exported OTel trace (OTLP/JSON or a flat span array)? No vendor
account or datasource needed — upload it, get a Flow analysis link:

```bash
gigaflow login                  # sign in (hosted backend)
gigaflow ingest trace.json      # upload → analyze → opens the Flow viewer
```

`ingest` auto-detects the exporter (Arize, Logfire, …); pass `--exporter` to
override, `--label` to name the trace, `--no-wait` to skip waiting for the
analysis, and `-` to read from stdin.

## The end-to-end flow

```bash
# 1. Connect a trace source (creates a project + registers a datasource).
#    All five vendors are wizard-driven; → see docs/sources/<vendor>.md
gigaflow setup                  # interactive vendor wizard

# 2. Pull traces into GigaFlow.
gigaflow sync

# 3. Compute Flow for every trace that doesn't have results yet.
gigaflow compute "SELECT trace_id FROM trace_metrics WHERE run_id IS NULL"

# 4. Open a trace in the browser viewer (Trace / Orchestration / Atomic / Metrics).
gigaflow inspect <trace_id>
```

## Supported tracing backends

`gigaflow setup` walks you through connecting one of:

- **Arize Phoenix** — PostgreSQL connection to the Phoenix spans DB
- **Braintrust** — API base URL + project name + API key
- **Logfire** — API base URL + read token
- **MLflow** — tracking server URL (+ optional token)
- **W&B Weave** — trace server URL + `<entity>/<project>` + W&B API key

Each gets a built-in transform; Braintrust/MLflow/Arize work out of the box; Logfire works out of the box for pydantic-ai projects; W&B Weave ships a template you tailor to your op names. The wizard previews how your spans classified so you can spot a mismatch immediately.

## Connect your trace source

Pick your platform — each guide covers the exact datasource config + whether a
custom transform is needed:

| Source | Setup | Bundled transform? | Guide |
|---|---|---|---|
| **Arize Phoenix** | `gigaflow setup` wizard | ✅ yes | [docs/sources/arize-phoenix.md](docs/sources/arize-phoenix.md) |
| **Logfire** | `gigaflow setup` wizard | ✅ yes | [docs/sources/logfire.md](docs/sources/logfire.md) |
| **Braintrust** | `gigaflow setup` wizard | ✅ yes | [docs/sources/braintrust.md](docs/sources/braintrust.md) |
| **MLflow** | `gigaflow setup` wizard | ✅ yes | [docs/sources/mlflow.md](docs/sources/mlflow.md) |
| **W&B Weave** | `gigaflow setup` wizard | ⚠️ template (see note) | [docs/sources/wb-weave.md](docs/sources/wb-weave.md) |
| **Direct OTLP** | project token + exporter | n/a (per-project transform) | [docs/sources/otlp.md](docs/sources/otlp.md) |

> `gigaflow setup` supports all five vendors. W&B Weave ships a template transform
> (`wb_weave.yml`) rather than a fully generic one — Weave has no structural span-type
> field, so you may need to tailor filter rules to your op names. The setup wizard
> previews classification so you can spot a mismatch immediately.

## Commands

| Command | What it does |
|---|---|
| `gigaflow ingest <trace.json>` | Upload a local OTel trace export, run Flow analysis, get a viewer link (`-` reads stdin) |
| `gigaflow setup` | First-run wizard (all five vendors): pick vendor, enter connection, name project, upload transform, sync, preview |
| `gigaflow sync` | Pull traces from the configured datasource (append-only) |
| `gigaflow traces` | List traces (auto-syncs first) |
| `gigaflow spans <trace_id>` | List spans for a trace |
| `gigaflow compute "<SQL>"` | Batch-compute Flow for matching traces |
| `gigaflow inspect <trace_id>` | Open the browser viewer |
| `gigaflow query "<SQL>"` | Run SQL against the `trace_metrics` view (read-only) — see [QUERYING.md](QUERYING.md) |
| `gigaflow config show` / `clear` | Show / reset saved config |

## Transform configs

A **transform config** (YAML) maps a source's raw spans to GigaFlow primitives
(`llm_call`, `tool_invocation`, `user_input`, `transform`) via `filter` (classify)
and `mapping` (extract fields). Bundled configs ship for all five vendors
(`gigaflow/transforms/`); W&B Weave's is a template you may need to tailor to your
op names. Leave the transform prompt blank in `gigaflow setup` to use the bundled
one. Re-upload to an existing project without re-running setup:

```bash
curl -X PUT "$GIGAFLOW_BACKEND_URL/projects/<project_id>/transform" \
  -H "Authorization: Bearer $GIGAFLOW_API_KEY" \
  -H "Content-Type: text/plain" --data-binary @my_transform.yml
```

Re-`sync` after changing a transform to reclassify spans.

Full grammar + the per-project upload flow: [docs/transforms.md](docs/transforms.md).
