gigaflow 0.1.0__tar.gz

gigaflow-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: gigaflow
+Version: 0.1.0
+Summary: GigaFlow CLI — connect Arize Phoenix traces to GigaFlow and analyze them
+Author: GigaFlow Team
+License: MIT
+Project-URL: Homepage, https://github.com/GigaFlow-AI/gigaflow
+Project-URL: Repository, https://github.com/GigaFlow-AI/gigaflow
+Keywords: gigaflow,arize,phoenix,llm,observability,tracing,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT 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
+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"
+
+# gigaflow CLI
+
+Command-line interface for GigaFlow — connect Arize Phoenix traces to GigaFlow and analyze them with Atomic Information Flow (AIF).
+
+## Install
+
+```bash
+pip install gigaflow
+```
+
+Or from source:
+
+```bash
+cd cli && pip install -e .
+```
+
+## Usage
+
+```bash
+gigaflow setup                                           # Connect to Arize Phoenix datasource
+gigaflow traces                                          # List traces (auto-syncs first)
+gigaflow spans <trace_id>                                # List spans for a trace
+gigaflow aif run <trace_id>                              # Run AIF analysis
+gigaflow aif run <trace_id> --model gpt-4o --show-atoms
+gigaflow sync                                            # Re-sync from datasource
+gigaflow config show                                     # Show saved config
+gigaflow config clear                                    # Reset config
+```
+
+## Transform config
+
+GigaFlow maps raw Arize Phoenix spans to its own primitives (`llm_call`, `tool_invocation`, `user_input`) using a YAML transform config.
+
+The built-in config for Arize Phoenix is at:
+
+```
+gigaflow/transforms/arize_phoenix.yml
+```
+
+It maps the OpenInference span columns (`span_kind`, `attributes.*`) to the fields that AIF reads. If your Arize setup uses different attribute paths, copy the file, edit it, and provide the path during `gigaflow setup` when prompted:
+
+```
+Path to transform.yml (leave blank for built-in Arize Phoenix config): /path/to/my_transform.yml
+```
+
+You can also re-upload a transform config to an existing project without re-running the full wizard:
+
+```bash
+curl -X PUT http://localhost:8000/api/v1/projects/<project_id>/transform \
+  -H "Content-Type: text/plain" \
+  --data-binary @my_transform.yml
+```
+
+After changing the transform config, re-sync to reclassify your spans:
+
+```bash
+gigaflow sync
+```
+
+### Transform config format
+
+```yaml
+version: "1.0"
+source: arize_phoenix
+
+primitives:
+  llm_call:
+    filter:
+      field: span_kind        # top-level DB column
+      value: "LLM"
+    mapping:
+      completion: attributes.output.value          # read by AIF for response atoms
+      model: attributes.llm.model_name
+
+  tool_invocation:
+    filter:
+      field: span_kind
+      value: "TOOL"
+    mapping:
+      tool_output: attributes.output.value         # read by AIF for tool atoms
+      tool_name: attributes.tool.name
+
+  user_input:
+    filter:
+      field: span_kind
+      value: "CHAIN"
+    mapping:
+      content: attributes.input.value              # read by AIF for the user query
+```
+
+Mapping values are dot-notation paths traversed against each span row. Nested JSON columns (e.g. `attributes`) are parsed automatically.
+
+## Publish to PyPI
+
+```bash
+cd cli
+pip install build twine
+python -m build
+twine upload dist/*
+```

gigaflow-0.1.0/README.md

@@ -0,0 +1,100 @@
+# gigaflow CLI
+
+Command-line interface for GigaFlow — connect Arize Phoenix traces to GigaFlow and analyze them with Atomic Information Flow (AIF).
+
+## Install
+
+```bash
+pip install gigaflow
+```
+
+Or from source:
+
+```bash
+cd cli && pip install -e .
+```
+
+## Usage
+
+```bash
+gigaflow setup                                           # Connect to Arize Phoenix datasource
+gigaflow traces                                          # List traces (auto-syncs first)
+gigaflow spans <trace_id>                                # List spans for a trace
+gigaflow aif run <trace_id>                              # Run AIF analysis
+gigaflow aif run <trace_id> --model gpt-4o --show-atoms
+gigaflow sync                                            # Re-sync from datasource
+gigaflow config show                                     # Show saved config
+gigaflow config clear                                    # Reset config
+```
+
+## Transform config
+
+GigaFlow maps raw Arize Phoenix spans to its own primitives (`llm_call`, `tool_invocation`, `user_input`) using a YAML transform config.
+
+The built-in config for Arize Phoenix is at:
+
+```
+gigaflow/transforms/arize_phoenix.yml
+```
+
+It maps the OpenInference span columns (`span_kind`, `attributes.*`) to the fields that AIF reads. If your Arize setup uses different attribute paths, copy the file, edit it, and provide the path during `gigaflow setup` when prompted:
+
+```
+Path to transform.yml (leave blank for built-in Arize Phoenix config): /path/to/my_transform.yml
+```
+
+You can also re-upload a transform config to an existing project without re-running the full wizard:
+
+```bash
+curl -X PUT http://localhost:8000/api/v1/projects/<project_id>/transform \
+  -H "Content-Type: text/plain" \
+  --data-binary @my_transform.yml
+```
+
+After changing the transform config, re-sync to reclassify your spans:
+
+```bash
+gigaflow sync
+```
+
+### Transform config format
+
+```yaml
+version: "1.0"
+source: arize_phoenix
+
+primitives:
+  llm_call:
+    filter:
+      field: span_kind        # top-level DB column
+      value: "LLM"
+    mapping:
+      completion: attributes.output.value          # read by AIF for response atoms
+      model: attributes.llm.model_name
+
+  tool_invocation:
+    filter:
+      field: span_kind
+      value: "TOOL"
+    mapping:
+      tool_output: attributes.output.value         # read by AIF for tool atoms
+      tool_name: attributes.tool.name
+
+  user_input:
+    filter:
+      field: span_kind
+      value: "CHAIN"
+    mapping:
+      content: attributes.input.value              # read by AIF for the user query
+```
+
+Mapping values are dot-notation paths traversed against each span row. Nested JSON columns (e.g. `attributes`) are parsed automatically.
+
+## Publish to PyPI
+
+```bash
+cd cli
+pip install build twine
+python -m build
+twine upload dist/*
+```

gigaflow-0.1.0/gigaflow/__init__.py

@@ -0,0 +1 @@
+"""GigaFlow CLI package."""

gigaflow-0.1.0/gigaflow/_config.py

@@ -0,0 +1,24 @@
+"""Persistent CLI configuration stored in ~/.gigaflow/config.json."""
+
+import json
+from pathlib import Path
+
+CONFIG_PATH = Path.home() / ".gigaflow" / "config.json"
+
+
+def load() -> dict:
+    if not CONFIG_PATH.exists():
+        return {}
+    with open(CONFIG_PATH) as f:
+        return json.load(f)
+
+
+def save(config: dict):
+    CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    with open(CONFIG_PATH, "w") as f:
+        json.dump(config, f, indent=2)
+
+
+def clear():
+    if CONFIG_PATH.exists():
+        CONFIG_PATH.unlink()

gigaflow-0.1.0/gigaflow/_fmt.py

@@ -0,0 +1,78 @@
+"""Terminal formatting: headers, prompts, tables."""
+
+import getpass
+import sys
+
+WIDTH = 62
+
+
+def header(title: str):
+    print()
+    print("=" * WIDTH)
+    print(f"  {title}")
+    print("=" * WIDTH)
+
+
+def section(title: str):
+    pad = max(0, WIDTH - len(title) - 4)
+    print(f"\n── {title} {'─' * pad}")
+
+
+def ok(msg: str):
+    print(f"  ✓  {msg}")
+
+
+def fail(msg: str):
+    print(f"  ✗  {msg}", file=sys.stderr)
+
+
+def info(msg: str):
+    print(f"     {msg}")
+
+
+def prompt(label: str, default: str = "", required: bool = False) -> str:
+    suffix = f" [{default}]" if default else ""
+    while True:
+        try:
+            val = input(f"  {label}{suffix}: ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print()
+            sys.exit(0)
+        result = val if val else default
+        if result or not required:
+            return result
+        print(f"     {label} is required.")
+
+
+def prompt_password(label: str) -> str:
+    try:
+        return getpass.getpass(f"  {label}: ")
+    except (EOFError, KeyboardInterrupt):
+        print()
+        sys.exit(0)
+
+
+def table(rows: list, headers: list, max_col: int = 38):
+    """Print a simple fixed-width table."""
+    if not rows:
+        print("  (no results)")
+        return
+
+    widths = [len(h) for h in headers]
+    for row in rows:
+        for i, cell in enumerate(row):
+            widths[i] = min(max(widths[i], len(str(cell))), max_col)
+
+    fmt = "  " + "  ".join(f"{{:<{w}}}" for w in widths)
+    sep = "  " + "  ".join("─" * w for w in widths)
+
+    print()
+    print(fmt.format(*headers))
+    print(sep)
+    for row in rows:
+        cells = []
+        for i, cell in enumerate(row):
+            s = str(cell) if cell is not None else "-"
+            cells.append(s[: widths[i] - 1] + "…" if len(s) > widths[i] else s)
+        print(fmt.format(*cells))
+    print()

gigaflow-0.1.0/gigaflow/_http.py

@@ -0,0 +1,24 @@
+"""Minimal HTTP client (stdlib only)."""
+
+import json
+import urllib.error
+import urllib.request
+
+
+def api(base_url: str, method: str, path: str, body=None, content_type: str = "application/json"):
+    data = None
+    if body is not None:
+        data = body.encode() if isinstance(body, str) else json.dumps(body).encode()
+    req = urllib.request.Request(f"{base_url}{path}", data=data, method=method)
+    req.add_header("Content-Type", content_type)
+    try:
+        with urllib.request.urlopen(req) as resp:
+            return resp.status, json.loads(resp.read())
+    except urllib.error.HTTPError as e:
+        raw = e.read()
+        try:
+            return e.code, json.loads(raw)
+        except Exception:
+            return e.code, {"error": raw.decode()}
+    except urllib.error.URLError as e:
+        return None, {"error": str(e.reason)}

gigaflow-0.1.0/gigaflow/_setup.py

@@ -0,0 +1,230 @@
+"""Interactive setup wizard: project creation, transform upload, datasource registration, sync."""
+
+import importlib.resources
+import sys
+
+from gigaflow import _config, _fmt
+from gigaflow._http import api
+
+
+def _load_default_transform() -> str:
+    """Load the built-in Arize Phoenix transform config from the package."""
+    ref = importlib.resources.files("gigaflow.transforms").joinpath("arize_phoenix.yml")
+    return ref.read_text(encoding="utf-8")
+
+
+def load_env_file(path: str) -> dict:
+    """Parse a .env-style file and return key-value pairs.
+
+    Supports comments (#), blank lines, and optionally quoted values.
+    """
+    env: dict[str, str] = {}
+    try:
+        with open(path) as f:
+            for line in f:
+                line = line.strip()
+                if not line or line.startswith("#"):
+                    continue
+                if "=" not in line:
+                    continue
+                key, _, value = line.partition("=")
+                key = key.strip()
+                value = value.strip()
+                if len(value) >= 2 and value[0] == value[-1] and value[0] in ('"', "'"):
+                    value = value[1:-1]
+                if key:
+                    env[key] = value
+    except OSError as e:
+        _fmt.fail(f"Could not read env file: {e}")
+    return env
+
+ARIZE_TRANSFORM_YAML = _load_default_transform()
+
+
+def check_backend(base_url: str) -> bool:
+    status, resp = api(base_url, "GET", "/health")
+    if status is None:
+        _fmt.fail(f"Could not reach gigaflow backend at {base_url}")
+        _fmt.info("Make sure the backend is running:  cd backend && make run")
+        return False
+    if status != 200:
+        _fmt.fail(f"Backend returned {status}: {resp}")
+        return False
+    _fmt.ok(f"Backend reachable at {base_url}")
+    return True
+
+
+def create_project(base_url: str, name: str) -> str | None:
+    status, resp = api(base_url, "POST", "/projects/", {"name": name})
+    if status != 200:
+        _fmt.fail(f"Failed to create project ({status}): {resp}")
+        return None
+    project_id = resp["project_id"]
+    _fmt.ok(f"Project created: {name}")
+    _fmt.info(f"project_id: {project_id}")
+    return project_id
+
+
+def upload_transform(base_url: str, project_id: str, yaml_content: str = ARIZE_TRANSFORM_YAML) -> bool:
+    status, resp = api(
+        base_url, "PUT", f"/projects/{project_id}/transform",
+        yaml_content, content_type="text/plain",
+    )
+    if status != 200:
+        _fmt.fail(f"Failed to upload transform config ({status}): {resp}")
+        return False
+    primitives = list(resp.get("transform_config", {}).get("primitives", {}).keys())
+    _fmt.ok("Transform config uploaded")
+    _fmt.info(f"primitives: {', '.join(primitives)}")
+    return True
+
+
+def register_datasource(base_url: str, project_id: str, connection_url: str, source_table: str) -> str | None:
+    status, resp = api(base_url, "POST", "/datasources/", {
+        "project_id": project_id,
+        "name": "arize-phoenix",
+        "connection_url": connection_url,
+        "source_table": source_table,
+    })
+    if status != 200:
+        _fmt.fail(f"Failed to register datasource ({status}): {resp}")
+        return None
+    datasource_id = resp["datasource_id"]
+    _fmt.ok("Datasource registered")
+    _fmt.info(f"datasource_id: {datasource_id}")
+    return datasource_id
+
+
+def do_sync(base_url: str, datasource_id: str) -> tuple[int, int] | None:
+    status, resp = api(base_url, "POST", f"/datasources/{datasource_id}/sync")
+    if status != 200:
+        _fmt.fail(f"Sync failed ({status}): {resp.get('detail', resp)}")
+        detail = str(resp.get("detail", ""))
+        if "connect" in detail.lower() or status == 502:
+            _fmt.info("Could not connect to the source database.")
+            _fmt.info("If Arize is running in Docker, try 'host.docker.internal' as the host.")
+        return None
+    synced_traces = resp.get("synced_traces", 0)
+    synced_spans = resp.get("synced_spans", 0)
+    _fmt.ok(f"Sync complete: {synced_traces} trace(s), {synced_spans} span(s)")
+    return synced_traces, synced_spans
+
+
+def run_wizard(base_url: str) -> dict | None:
+    """
+    Interactive wizard. Returns saved config dict on success, None on failure.
+    """
+    _fmt.header("GigaFlow Setup Wizard")
+
+    # ── Env file (optional) ───────────────────────────────────────────────────
+    env_path = _fmt.prompt("Path to gigaflow.env (leave blank to enter values manually)")
+    if env_path:
+        env = load_env_file(env_path)
+        if env:
+            _fmt.ok(f"Loaded env file: {env_path}")
+    else:
+        env = {}
+
+    # ── Step 1: backend ───────────────────────────────────────────────────────
+    _fmt.section("Step 1: GigaFlow backend")
+    if not check_backend(base_url):
+        return None
+
+    # ── Step 2: project ───────────────────────────────────────────────────────
+    _fmt.section("Step 2: Project")
+    project_name = _fmt.prompt("Project name", env.get("GIGAFLOW_PROJECT_NAME", "arize-phoenix-project"))
+    project_id = create_project(base_url, project_name)
+    if not project_id:
+        return None
+
+    transform_path = _fmt.prompt(
+        "Path to transform.yml (leave blank for built-in Arize Phoenix config)",
+        env.get("GIGAFLOW_TRANSFORM_YML", ""),
+    )
+    if transform_path:
+        try:
+            with open(transform_path) as f:
+                yaml_content = f.read()
+            _fmt.ok(f"Loaded transform file: {transform_path}")
+        except OSError as e:
+            _fmt.fail(f"Could not read transform file: {e}")
+            return None
+    else:
+        yaml_content = ARIZE_TRANSFORM_YAML
+        _fmt.info("Using built-in Arize Phoenix transform config")
+
+    if not upload_transform(base_url, project_id, yaml_content):
+        return None
+
+    # ── Step 3: Arize Phoenix DB ──────────────────────────────────────────────
+    _fmt.section("Step 3: Arize Phoenix database")
+    print()
+    print("  Enter the connection details for the PostgreSQL database")
+    print("  that Arize Phoenix writes to.")
+    print()
+    print("  Tip: if GigaFlow is running in Docker (the default),")
+    print("  use 'host.docker.internal' to reach the host machine.")
+    print()
+    print("  Find the Arize DB port with:")
+    print("    docker ps --filter name=arize_agent_example-db --format '{{.Ports}}'")
+    print()
+
+    host  = _fmt.prompt("Host", env.get("GIGAFLOW_DB_HOST", "host.docker.internal"))
+    port  = _fmt.prompt("Port", env.get("GIGAFLOW_DB_PORT", ""), required=True)
+    user  = _fmt.prompt("User", env.get("GIGAFLOW_DB_USER", "postgres"))
+
+    if env.get("GIGAFLOW_DB_PASSWORD"):
+        password = env["GIGAFLOW_DB_PASSWORD"]
+        _fmt.info("Password: [from env file]")
+    else:
+        password = _fmt.prompt_password("Password")
+
+    db    = _fmt.prompt("Database",     env.get("GIGAFLOW_DB_NAME", "postgres"))
+    table = _fmt.prompt("Source table", env.get("GIGAFLOW_DB_TABLE", "spans"))
+
+    connection_url = f"postgresql://{user}:{password}@{host}:{port}/{db}"
+
+    # ── Step 4: register + sync ───────────────────────────────────────────────
+    _fmt.section("Step 4: Register datasource & sync")
+    datasource_id = register_datasource(base_url, project_id, connection_url, table)
+    if not datasource_id:
+        return None
+
+    result = do_sync(base_url, datasource_id)
+    if result is None:
+        return None
+
+    synced_traces, _ = result
+    if synced_traces > 0:
+        _show_span_preview(base_url, project_id)
+
+    config: dict = {
+        "backend_url": base_url,
+        "project_id": project_id,
+        "datasource_id": datasource_id,
+    }
+    _config.save(config)
+    _fmt.ok(f"Configuration saved to {_config.CONFIG_PATH}")
+    return config
+
+
+def _show_span_preview(base_url: str, project_id: str):
+    status, resp = api(base_url, "GET", f"/traces/?project_id={project_id}")
+    if status != 200:
+        return
+    traces = resp.get("traces", [])
+    if not traces:
+        return
+    trace_id = traces[0]["trace_id"]
+    status, resp = api(base_url, "GET", f"/traces/{trace_id}/spans")
+    if status != 200:
+        return
+    spans = resp if isinstance(resp, list) else resp.get("spans", [])
+    classified = [s for s in spans if s.get("primitive_type")]
+    unclassified = [s for s in spans if not s.get("primitive_type")]
+    _fmt.info(f"Sample trace — {len(classified)} classified, {len(unclassified)} unclassified")
+    for ptype in ["llm_call", "tool_invocation", "user_input"]:
+        match = next((s for s in spans if s.get("primitive_type") == ptype), None)
+        if match:
+            pd = match.get("primitive_data") or {}
+            _fmt.info(f"  {ptype}: {pd}")

gigaflow-0.1.0/gigaflow/cli.py

@@ -0,0 +1,90 @@
+"""
+gigaflow — CLI entry point.
+
+Commands:
+  gigaflow run aif [TRACE_ID]        Run AIF analysis (interactive if TRACE_ID omitted)
+  gigaflow setup                     Configure GigaFlow with an Arize Phoenix datasource
+  gigaflow sync                      Re-sync traces from the configured datasource
+  gigaflow traces                    List all traces (auto-syncs first)
+  gigaflow spans <trace_id>          List spans for a trace (auto-syncs first)
+  gigaflow inspect <trace_id>        Visualize a trace (orchestration graph + full span data)
+  gigaflow projects                  List all projects
+  gigaflow config show               Show saved configuration
+  gigaflow config clear              Clear saved configuration
+"""
+
+import argparse
+import os
+import sys
+
+from gigaflow import _config
+from gigaflow._setup import load_env_file
+from gigaflow.commands import config, inspect, projects, run, setup, traces
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="gigaflow",
+        description="GigaFlow CLI — connect Arize Phoenix traces to GigaFlow and analyze them.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+examples:
+  gigaflow run aif
+  gigaflow run aif <trace_id>
+  gigaflow setup
+  gigaflow traces
+  gigaflow spans <trace_id>
+  gigaflow inspect <trace_id>
+  gigaflow inspect <trace_id> --cli
+  gigaflow inspect <trace_id> --port 8080
+  gigaflow sync
+  gigaflow config show
+  gigaflow config clear
+        """,
+    )
+    parser.add_argument(
+        "--backend",
+        metavar="URL",
+        default=None,
+        help="GigaFlow API base URL (default: from config or http://localhost:8000/api/v1)",
+    )
+    parser.add_argument(
+        "--env-file",
+        metavar="PATH",
+        default=None,
+        help="Path to gigaflow.env (default: auto-detects gigaflow.env in current directory)",
+    )
+
+    sub = parser.add_subparsers(dest="command", metavar="<command>")
+    run.register(sub)
+    setup.register(sub)
+    traces.register(sub)
+    inspect.register(sub)
+    projects.register(sub)
+    config.register(sub)
+
+    return parser
+
+
+def main():
+    parser = _build_parser()
+    args = parser.parse_args()
+
+    if not hasattr(args, "func"):
+        parser.print_help()
+        sys.exit(0)
+
+    # Load gigaflow.env and inject keys into os.environ (without overriding existing vars)
+    env_file = args.env_file or ("gigaflow.env" if os.path.exists("gigaflow.env") else None)
+    if env_file:
+        for key, value in load_env_file(env_file).items():
+            os.environ.setdefault(key, value)
+
+    cfg = _config.load()
+    base_url = (args.backend or cfg.get("backend_url") or "http://localhost:8000/api/v1").rstrip("/")
+
+    args.func(args, base_url)
+
+
+if __name__ == "__main__":
+    main()

gigaflow-0.1.0/gigaflow/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command modules — one file per top-level command group."""