datagoat-decide 0.2.0__py3-none-any.whl

datagoat_decide/__init__.py

@@ -0,0 +1,5 @@
+"""Datagoat: let Datagoat answer a decision step in your agent, with your AI as the fallback."""
+from .client import Datagoat, Decision, DecisionOutput
+
+__all__ = ["Datagoat", "Decision", "DecisionOutput"]
+__version__ = "0.2.0"

datagoat_decide/cli.py

@@ -0,0 +1,279 @@
+"""datagoat-decide: connect an agent to Datagoat.
+
+  scan [path] | scan --traces FILE   find decision steps in source (never imported) or in traces
+  install                            add the MCP server and skill to your coding agents
+  history FILE.csv                   past cases with outcomes (or with --events, outcomes from a log)
+  backfill TRACES                    past decisions of your AI, from traces, so a point starts with a record
+  outcomes EVENTS.csv                outcomes for recorded decisions, from a raw event log
+  map module:attr                    read a compiled LangGraph"""
+from __future__ import annotations
+
+import argparse
+import importlib
+import json
+import os
+import sys
+
+from .client import Datagoat
+from .install import CLIENTS, install
+from .scan import scan
+
+
+def _print_scan(body, proposals=None) -> None:
+    steps = body["steps"]
+    if not steps:
+        print("No decision steps found: no model call here returns a yes/no, a fixed set of values or a bounded score.")
+        return
+    by_step = {p["step_id"]: p for p in (proposals or [])}
+    print(f"Found {len(steps)} decision step(s) ({body['framework']}):")
+    for s in steps:
+        p = by_step.get(s["id"])
+        loc = f"{s['location']['file']}:{s['location']['line']}" if s.get("location") else (s.get("note") or "")
+        status = (p or {}).get("status") or ("wired" if s.get("wired_point") else "new")
+        point = (p or {}).get("point") or s.get("wired_point") or s["proposed_point"]
+        what = ""
+        if p:
+            what = f"choice of {', '.join(p['options'])}" if p["question"] == "choice" else (
+                f"yes/no, tiers {'/'.join(p['tier_labels'])}" if p.get("tier_labels") else "yes/no")
+        else:
+            what = ", ".join(f"{f['name']} ({f['kind']})" for f in s["fields"]) or "schema in trace"
+        print(f"  [{status}] {point}  {loc}  {s['framework']}/{s['scope']}  {what}")
+
+
+def _event_args(p, prefix: str, required: bool) -> None:
+    if prefix:
+        p.add_argument("--events", metavar="FILE", help="event log CSV (case id, event, time) to take outcomes from")
+    p.add_argument(f"--{prefix}case-id" if prefix else "--case-id", dest="ev_case_id", required=required and not prefix,
+                   help="event log column with the case id" + (" (default: --case-id)" if prefix else ""))
+    p.add_argument(f"--{prefix}name" if prefix else "--event", dest="ev_event", required=required, help="event log column with the event name")
+    p.add_argument(f"--{prefix}time" if prefix else "--time", dest="ev_time", required=required, help="event log column with when it happened")
+    p.add_argument("--yes", dest="ev_yes", required=required, help="comma-separated events that mean the outcome happened")
+    p.add_argument("--no", dest="ev_no", help="comma-separated events that mean it did not (optional)")
+
+
+def _split(v):
+    return [x.strip() for x in v.split(",") if x.strip()] if v else []
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="datagoat-decide")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    sc = sub.add_parser("scan", help="find decision steps in source code without importing it")
+    sc.add_argument("path", nargs="?", default=".")
+    sc.add_argument("--name", help="agent name shown in the dashboard (default: the folder name)")
+    sc.add_argument("--json", action="store_true", help="print the agent map as JSON")
+    sc.add_argument("--send", action="store_true", help="send the map to Datagoat (DATAGOAT_API_KEY) and print its proposals")
+    sc.add_argument("--traces", metavar="FILE", help="read an exported trace file (OTLP JSON, LangSmith runs, Langfuse observations) instead of source")
+    sc.add_argument("--min-runs", type=int, default=5, help="traces: runs a step needs before its outputs are read (default 5)")
+    ins = sub.add_parser("install", help="connect your coding agents (Claude Code, Cursor, VS Code, Codex, Gemini, Windsurf) to Datagoat")
+    ins.add_argument("--url", help="your Datagoat URL (default: DATAGOAT_BASE_URL)")
+    ins.add_argument("--client", help="comma-separated: " + ", ".join(CLIENTS) + ", or all (default: detected)")
+    ins.add_argument("--auth", choices=["oauth", "key"], default="oauth", help="oauth: sign in from the client; key: read DATAGOAT_API_KEY")
+    ins.add_argument("--dir", default=".")
+    ins.add_argument("--dry-run", action="store_true")
+    h = sub.add_parser("history", help="import past cases with outcomes from a CSV export for a declared point")
+    h.add_argument("file")
+    h.add_argument("--point", required=True)
+    h.add_argument("--case-id", required=True, help="column that identifies a case (the point's entity)")
+    h.add_argument("--time", required=True, help="column with when each case happened")
+    h.add_argument("--outcome", help="the outcome column (or give --events)")
+    h.add_argument("--positive", default="1", help='value of the outcome column that means it happened (default "1"; case-insensitive)')
+    h.add_argument("--fields", help="comma-separated input columns (default: every other column); use the point's input fields")
+    h.add_argument("--dry-run", action="store_true", help="read and count, send nothing")
+    _event_args(h, prefix="event-", required=False)
+    h.add_argument("--horizon-days", type=int, help="with --events: the point's horizon (days from a case to its outcome)")
+
+    o = sub.add_parser("outcomes", help="send outcomes for recorded decisions from a raw event log (case id, event, time)")
+    o.add_argument("file")
+    o.add_argument("--point", required=True)
+    _event_args(o, prefix="", required=True)
+    o.add_argument("--dry-run", action="store_true")
+
+    b = sub.add_parser("backfill", help="send past decisions of your AI, from an exported trace file, as the point's record")
+    b.add_argument("file")
+    b.add_argument("--point", required=True)
+    b.add_argument("--step", help="span / run name of the decision step (default: the only decision step found)")
+    b.add_argument("--case-id", required=True, help="input field (dotted path ok) that identifies a case")
+    b.add_argument("--fields", required=True, help="comma-separated input fields to send: the point's input fields. Nothing else leaves this machine")
+    b.add_argument("--acted-when", metavar="FIELD=V1,V2", help="yes/no points: the AI acted when this output field has one of these values (default: read a bool field)")
+    b.add_argument("--option-from", metavar="FIELD", help="choice points: the output field with the option used")
+    b.add_argument("--dry-run", action="store_true")
+    m = sub.add_parser("map", help="map a compiled LangGraph: module.path:attribute (a graph, or a function returning one)")
+    m.add_argument("target")
+    m.add_argument("--name", help="agent name shown in the dashboard")
+    m.add_argument("--dry-run", action="store_true", help="print the map instead of sending it")
+    a = ap.parse_args(argv)
+
+    if a.cmd == "scan":
+        if a.traces:
+            from .traces import detect, load
+            runs = load(a.traces)
+            body = detect(runs, agent=a.name or os.path.splitext(os.path.basename(a.traces))[0], min_runs=a.min_runs)
+            if not a.json:
+                print(f"Read {len(runs)} spans/runs from {a.traces}.")
+        else:
+            body = scan(a.path, name=a.name)
+        if a.send:
+            if not body["steps"]:
+                _print_scan(body)
+                return 1
+            res = Datagoat().post_agent_map(body)
+            if a.json:
+                print(json.dumps(res, indent=2))
+            else:
+                _print_scan(body, res.get("proposals"))
+                print(f"agent_id {res.get('agent_id')}")
+            return 0
+        if a.json:
+            print(json.dumps(body, indent=2))
+        else:
+            _print_scan(body)
+        return 0
+
+    if a.cmd == "history":
+        from .history_csv import prepare
+        if not a.outcome and not a.events:
+            print("Give --outcome (a column in the file) or --events (an event log to take outcomes from).")
+            return 2
+        p = prepare(a.file, a.case_id, a.time, None if a.events else a.outcome, a.positive, _split(a.fields) or None)
+        if p["missing_columns"]:
+            print(f"Missing from the file: {', '.join(p['missing_columns'])}.")
+            return 2
+        rows, sk = p["rows"], p["skipped"]
+        if a.events:
+            from .events import _dt, label_case, read_events
+            if not (a.ev_event and a.ev_time and a.ev_yes and a.horizon_days):
+                print("--events needs --event-name, --event-time, --yes and --horizon-days.")
+                return 2
+            ev = read_events(a.events, a.ev_case_id or a.case_id, a.ev_event, a.ev_time, _split(a.ev_yes), _split(a.ev_no))
+            if ev["missing_columns"]:
+                print(f"Missing from the event log: {', '.join(ev['missing_columns'])}.")
+                return 2
+            c = ev["counts"]
+            print(f"Event log: {c['rows']} events, {c['yes']} yes, {c['no']} no, {c['other']} other; last at {ev['last'].isoformat() if ev['last'] else 'none'}.")
+            labelled, still_open = [], 0
+            for r in rows:
+                y = label_case(_dt(r["at"]), ev["by_case"].get(r["case_id"], []), a.horizon_days, ev["last"])
+                if y is None:
+                    still_open += 1
+                else:
+                    labelled.append({**r, "outcome": y})
+            rows = labelled
+            sk = {**sk, "blank_outcome": still_open}
+        pos = sum(r["outcome"] for r in rows)
+        print(f"{len(rows)} cases ready, {pos} with the outcome; fields {', '.join(p['fields'])}.")
+        if any(sk.values()):
+            print(f"Left out: {sk['blank_outcome']} with no outcome yet, {sk['bad_time']} with an unreadable date, {sk['no_id']} with no {a.case_id}.")
+        if rows and pos in (0, len(rows)) and not a.events:
+            print(f'Warning: every case has the same outcome. Check --positive (values are compared to "{a.positive}").')
+        if a.dry_run or not rows:
+            return 0 if rows else 1
+        res = Datagoat().history(a.point, rows)
+        print(f"Imported {res['imported']} cases into {a.point}. Sending the file again is safe: a case sent twice replaces itself.")
+        return 0
+
+    if a.cmd == "outcomes":
+        from .events import outcomes_from_events, read_events
+        ev = read_events(a.file, a.ev_case_id, a.ev_event, a.ev_time, _split(a.ev_yes), _split(a.ev_no))
+        if ev["missing_columns"]:
+            print(f"Missing from the file: {', '.join(ev['missing_columns'])}.")
+            return 2
+        c = ev["counts"]
+        rows = outcomes_from_events(ev)
+        print(f"{c['rows']} events: {c['yes']} mean it happened, {c['no']} mean it did not, {c['other']} ignored; {len(ev['by_case'])} cases.")
+        if c["bad_time"] or c["no_id"]:
+            print(f"Left out: {c['bad_time']} with an unreadable time, {c['no_id']} with no case id.")
+        if a.dry_run or not rows:
+            return 0 if rows else 1
+        from .client import batches
+        dg, sent, matched = Datagoat(), 0, 0
+        for chunk in batches(rows):
+            r = dg.outcomes(a.point, chunk)
+            sent += r["accepted"]
+            matched += r["matched_decisions"]
+        print(f"Sent {sent} outcomes to {a.point}; {matched} cases match a recorded decision. Datagoat labels each decision by its horizon.")
+        return 0
+
+    if a.cmd == "backfill":
+        from .traces import backfill, detect, load
+        runs = load(a.file)
+        step = a.step
+        if not step:
+            found = [s["name"] for s in detect(runs)["steps"]]
+            if len(found) != 1:
+                print(f"Pass --step: {'decision steps in this file: ' + ', '.join(found) if found else 'no decision step found in this file'}.")
+                return 2
+            step = found[0]
+        acted = None
+        if a.acted_when:
+            f, _, vals = a.acted_when.partition("=")
+            acted = (f.strip(), _split(vals))
+        r = backfill(runs, step, a.case_id, _split(a.fields), flag_from=acted, option_from=a.option_from)
+        ds = r["decisions"]
+        print(f"{r['runs']} runs of {step}; {len(ds)} decisions ready" + (f"; left out: {', '.join(f'{v} {k}' for k, v in r['skipped'].items())}" if r["skipped"] else "") + ".")
+        if ds:
+            print(f"Fields: {', '.join(ds[0]['inputs'])}. First: {ds[0]['decided_at']}, last: {ds[-1]['decided_at']}.")
+            if not a.option_from and not any("flag" in d for d in ds):
+                print("Note: no yes/no read from the outputs. Pass --acted-when FIELD=VALUES so outcomes the AI prevented are not counted as real 0s.")
+            from datetime import datetime, timedelta, timezone
+            old = sum(1 for d in ds if d["decided_at"] < (datetime.now(timezone.utc) - timedelta(days=90)).isoformat().replace("+00:00", "Z"))
+            if old:
+                print(f"Note: {old} of them are more than 90 days old; refits read the last 90 days plus the horizon, so the oldest may not be used.")
+        if a.dry_run or not ds:
+            return 0 if ds else 1
+        res = Datagoat().backfill(a.point, ds)
+        print(f"Backfilled {res['inserted']} past decisions into {a.point} ({res['already_had']} were already there"
+              + (f", {res['logged_live']} skipped because the wrapped step already logged them" if res.get("logged_live") else "")
+              + (f", {res['unknown_option']} with an option that isn't declared" if res.get("unknown_option") else "") + ").")
+        if res.get("unflagged"):
+            print(f"Warning: {res['unflagged']} have no yes/no from your AI, so the ones it turned away will count as 'no'. Re-run with --acted-when.")
+        print("Now send their outcomes: datagoat-decide outcomes <events.csv> …")
+        return 0
+
+    if a.cmd == "install":
+        url = a.url or os.environ.get("DATAGOAT_BASE_URL")
+        if not url:
+            print("Pass --url with your Datagoat URL (shown on the dashboard's Connect page), or set DATAGOAT_BASE_URL.")
+            return 2
+        clients = CLIENTS if a.client == "all" else ([c.strip() for c in a.client.split(",") if c.strip()] if a.client else None)
+        bad = [c for c in clients or [] if c not in CLIENTS]
+        if bad:
+            print(f"Unknown client {', '.join(bad)}. One of: {', '.join(CLIENTS)}, all.")
+            return 2
+        d = os.path.abspath(a.dir)
+        changes = install(d, url, clients=clients, auth=a.auth, dry_run=a.dry_run)
+        for c in changes:
+            rel = os.path.relpath(c["file"], d)
+            print(f"{'would ' if a.dry_run else ''}{c['action']:<9} {c['file'] if rel.startswith('..') else rel}{'  ' + c['note'] if c.get('note') else ''}")
+        print("Set DATAGOAT_API_KEY where the client runs. Then restart it and ask it to connect this agent to Datagoat." if a.auth == "key"
+              else "Restart the client; it opens a sign-in the first time it uses Datagoat. Then ask it to connect this agent to Datagoat.")
+        return 1 if any(c["action"] == "manual" for c in changes) else 0
+
+    from .langgraph import map_graph  # needs langgraph importable; scan does not
+
+    mod_name, _, attr = a.target.partition(":")
+    sys.path.insert(0, ".")
+    obj = getattr(importlib.import_module(mod_name), attr or "graph")
+    graph = obj() if callable(obj) and not hasattr(obj, "get_graph") else obj
+    steps = map_graph(graph, module_prefix=mod_name.split(".")[-1])
+    body = {"name": a.name or mod_name, "framework": "langgraph", "steps": steps}
+    if a.dry_run:
+        print(json.dumps(body, indent=2))
+        return 0
+    res = Datagoat().post_agent_map(body)
+    found = [s for s in steps if s["kind"] == "decision"]
+    print(f"Mapped {len(steps)} steps, {len(found)} decision point(s): {', '.join(s['proposed_point'] for s in found) or 'none'}")
+    print(f"agent_id {res.get('agent_id')}")
+    return 0
+
+
+def run() -> int:
+    try:
+        return main()
+    except (RuntimeError, ValueError, FileNotFoundError) as e:
+        print(f"datagoat-decide: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(run())