The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the BIGHUB listing page.
Better decisions for IT agent actions.
BIGHUB turns proposed IT agent actions into better decisions before they run. It builds a Decision Packet, runs DecisionBrain, and surfaces an execution outcome: proceed when appropriate (can_run), pause for human review, ask for more context, or advise not to run—with an optional better_action before execution only when BIGHUB actually produced one.
For each proposed IT action (access changes, deployments, rotations, IAM updates, incidents, integrations), BIGHUB:
better_action when the backend proposes a distinct alternative—not a cosmetic rephrase of the originalexecution_mode (and legacy signals) into clear flags: can_run, needs_review, needs_more_context, should_not_rundecision.request_review(), SDK/MCP approvals) and first-class system integrations for GitHub, Sentry, Datadog, AWS CloudTrail, Terraform, Kubernetes, Argo CD, GitLab, Jenkins, Azure, Prometheus, Grafana, and OpenShiftThe recommended public flow:
proposed IT action → Decision Packet → DecisionBrain → (better_action when real) → execution_mode / flags → review or context when needed
Decision returnsHigh-level fields developers use most often:
| Field / idea | Meaning |
|---|---|
proposed_action | What your agent originally proposed |
better_action | Distinct backend alternative when present; None if no real alternative was produced (never trusted as “better” simply because it echoes the proposal) |
packet | Decision Packet: intent, system, constraints, candidates, risks, verification, etc., when returned |
brain | DecisionBrain: reasoning summary, confidence, regret, review hints, etc., when returned |
mode | SDK execution mode mapped from execution_mode and legacy payloads (for example review, needs_context, blocked) |
can_run, needs_review, needs_more_context, should_not_run | Operational guidance before you execute |
selected_model / model_selection | Routing when the backend actually selected a model or path—otherwise None / empty-ish structure (SDK does not invent routing) |
For full detail and /actions/evaluate field mapping, see sdk/python/README.md.
BIGHUB’s public SDK is centered on bighub.decide(...) and Decision Packet because the packet is the primitive that improves decision quality before execution.
On the April 2026 GPT-5.5 benchmark suite, BIGHUB improved average good decision rate from 41.11% to 73.14% across 21 cells, 2,520 labeled traces, and 5,040 LLM calls.
Same GPT-5.5 model, same frozen traces, same benchmark rubric. The baseline and packet arms differ only by whether the BIGHUB Decision Packet is included in the model input.
| View | Baseline GPT-5.5 | With BIGHUB | Uplift |
|---|---|---|---|
| IT incident | 71.95% | 91.67% | +19.72 pp |
| IT helpdesk | 40.28% | 82.78% | +42.50 pp |
| Incident coldstart | 71.39% | 85.56% | +14.17 pp |
| Incident large | 44.17% | 86.67% | +42.50 pp |
| Incident large coldstart | 44.45% | 75.55% | +31.11 pp |
| Refunds | 11.95% | 47.50% | +35.55 pp |
| Refunds large | 3.61% | 42.22% | +38.61 pp |
Good decision rate measures match to the benchmark-defined optimal action.
These benchmarks measure decision quality under a frozen authored benchmark contract. They do not claim guaranteed production business lift. The packet and rubric share the same benchmark ontology by design, which makes the decision surfaces auditable, but also means this is a framework-aligned evaluation rather than unconstrained production ground truth.
Why this matters for the SDK:
bighub.decide(...) is the ergonomic entrypoint for that packet-centered evaluation path.better_action is only present when the service returns a genuinely distinct recommendation—not on every trace, and not by simple paraphrase of proposed_action.selected_model / model_selection) appears when the backend actually performed selection; callers should tolerate None today.| Package | Language | Install | Description |
|---|---|---|---|
| bighub | Python | pip install bighub | Core Better Decision SDK — bighub.decide(...), Decision Packet / DecisionBrain helpers, reviews, optional outcomes. |
| bighub-openai | Python | pip install bighub-openai | OpenAI adapter — Better Decision layer on tool calls with @agent.action metadata. |
| @bighub/bighub-mcp | TypeScript | npm install @bighub/bighub-mcp | MCP server — bighub_decide and related tools for any MCP client. |
| bighub-anthropic | Python | — | Anthropic adapter — coming soon (readme). |
| bighub-openai (JS) | TypeScript | — | OpenAI adapter for Node.js — coming soon (readme). |
JavaScript-heavy workflows today: prefer the MCP server alongside your runtime.
When you choose to wire a learning loop later, report what happened after execution so future decisions improve:
Outcome reporting is not required for a first integration. The quickstart stays focused on the decision before execution.
When your org connects systems, the SDK can manage connections and polling so BIGHUB's world state reflects live infrastructure evidence:
Use client.systems.poll_metrics() and client.systems.poll_history("gitlab") to inspect poll health and redacted evidence.
Existing code can keep using BighubClient, AsyncBighubClient, and client.actions.evaluate(...) (evaluate payload / raw JSON paths). Older actions.submit flows remain documented in package-specific READMEs where relevant.
Prefer from bighub import Bighub + bighub.decide(...) for new IT agent integrations.
better_action is None unless BIGHUB returned a distinct recommended alternative—not a wording-only duplicate of proposed_action.selected_model and model_selection fields reflect real backend routing when present; otherwise None (SDK does not fabricate routing).decide → execute/review/context without calling report_outcome.allowed, recommendation, risk_score, result) for dashboard and older clients; the modern surface is can_run / needs_review / execution_mode and friends.sdk/python/README.md.