Metadata-Version: 2.4
Name: bighub
Version: 0.1.0b2
Summary: Better Decision SDK for IT agent actions with BIGHUB.
Project-URL: Homepage, https://bighub.io
Project-URL: GitHub, https://github.com/bighub-io/bighub
Project-URL: MCPServer, https://www.npmjs.com/package/@bighub/bighub-mcp
Project-URL: PyPI, https://pypi.org/project/bighub/
Project-URL: OpenAIAdapter, https://pypi.org/project/bighub-openai/
Author: BIGHUB_CEO
License: MIT License
        
        Copyright (c) BIGHUB
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: ai-agents,bighub,decision-learning,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx<1.0,>=0.27
Provides-Extra: dev
Requires-Dist: pytest-asyncio<1.0,>=0.23; extra == 'dev'
Requires-Dist: pytest<9.0,>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# BIGHUB SDK

Better decisions for IT agent actions.

> Beta release: this is the first public Better Decision SDK beta.

**BIGHUB helps AI agents and CI/CD workflows make better IT decisions before execution.**

It takes a proposed IT action, builds a **Decision Packet**, runs **DecisionBrain**, and returns execution guidance:

- proceed when appropriate
- pause for review
- ask for more context
- advise not to run
- suggest a real `better_action` only when the backend actually produced one

```bash
pip install --pre bighub
```

For future stable releases, use:

```bash
pip install bighub
```

Python 3.9+. Single dependency: `httpx`.

---

## Quick Start

```python
from bighub import Bighub


def run(action_to_run):
    raise NotImplementedError("Connect this to your executor.")


bighub = Bighub(api_key="your_api_key")

decision = bighub.decide(
    action="Roll out billing-api v3.12 to production",
    context={
        "system": "kubernetes",
        "environment": "production",
        "service": "billing-api",
        "ticket": "CHG-4401",
    },
)

if decision.needs_review:
    decision.request_review()
elif decision.needs_more_context:
    print("More context required:", decision.reason)
elif decision.should_not_run:
    print("Do not run:", decision.reason)
elif decision.can_run:
    action_to_run = decision.better_action or decision.proposed_action
    run(action_to_run)

bighub.close()
```

Recommended flow:

**proposed IT action -> Decision Packet -> DecisionBrain -> `better_action` when real -> execution mode and flags -> review or context when needed**

---

## When to use BIGHUB

Use BIGHUB before risky actions such as:

- GitHub Actions, GitLab CI, or Jenkins deploys
- `terraform apply`
- Argo CD sync or Kubernetes / OpenShift rollout
- Okta or IAM access changes
- credential rotation
- incident updates in Slack
- security gates after Trivy / Syft / SBOM signals
- production actions that may need review or additional context

If your workflow only reads data or performs harmless lookups, you probably do not need BIGHUB.

---

## What a `Decision` returns

High-value fields most workflows care about:

- `better_action`: a real backend-produced alternative when available, otherwise `None`
- `mode`: execution guidance such as `autonomous`, `constrained`, `review`, `blocked`, or `needs_context`
- `can_run`, `needs_review`, `needs_more_context`, `should_not_run`: direct operational flags
- `risk`: top-level risk score when provided
- `decision_path`: routing or evaluation path when provided
- `packet`: the `DecisionPacket` used for the decision
- `brain`: the `DecisionBrainResult` with reasoning summary, confidence, expected regret when provided, and related signals
- `selected_model`: present only when the backend actually selected one

For a smaller stable surface, use `decision.brief()`:

```python
brief = decision.brief()

if brief.can_run:
    run(brief.recommended_action)
elif brief.needs_review:
    print("Review required:", brief.reason)
```

---

## Honest behavior

The SDK is intentionally strict about what it does and does not invent:

- `better_action` is `None` unless BIGHUB returned a genuinely distinct recommendation
- `selected_model` is `None` unless the backend actually selected one
- `decision_path` and model-selection fields stay empty when the backend did not provide them
- outcomes are optional and not required for a first integration
- legacy `BighubClient` and `client.actions.evaluate(...)` remain available for existing integrations

If a backend `decision_packet` has no `packet_sha256`, the SDK computes a stable local hash and marks it with `packet.packet_sha256_is_local=True`.

---

## Optional: outcome reporting

If you want a learning loop later, report what happened after execution:

```python
decision.report_outcome(
    status="completed",
    evidence={"deployment_id": "dep_123"},
)
```

Outcome reporting is optional. The primary integration wedge is still the decision before execution.

---

## CI/CD and system integrations

You can connect system evidence so BIGHUB sees recent operational context before deciding.

For lower-level resources, `BighubClient` remains available:

```python
from bighub import BighubClient

client = BighubClient(api_key="your_api_key")

client.systems.save_connection(
    "gitlab",
    {
        "base_url": "https://gitlab.com",
        "gitlab_token": "glpat_...",
        "project_id": "123",
    },
    display_name="GitLab production",
)

client.systems.update_poll_schedule("gitlab", enabled=True, interval_seconds=300)
client.systems.poll("gitlab")
world = client.systems.world_state()

client.close()
```

System providers currently supported by the SDK/API include `okta`, `slack`, `github`, `datadog`, `sentry`, `aws_cloudtrail`, `terraform`, `kubernetes`, `argocd`, `gitlab`, `jenkins`, `azure`, `prometheus`, `grafana`, and `openshift`.

Poll snapshots and histories are redacted before persistence and exposure. They provide best-effort operational context; they are not a replacement for production monitoring.

Typical uses:

- gate a GitHub Actions or GitLab deploy with recent operational context
- inspect Kubernetes, Argo CD, Prometheus, or Grafana state before rollout
- apply IAM or Okta changes with better review posture
- incorporate security and incident signals before execution

---

## Compatibility

The modern entrypoint is `bighub.decide(...)`.

For existing integrations, legacy `BighubClient`, `client.actions.submit(...)`, and `client.actions.evaluate(...)` remain supported.

---

## Links

- [bighub.io](https://bighub.io)
- [GitHub repository](https://github.com/bighub-io/bighub)
- [Python examples](https://github.com/bighub-io/bighub/tree/main/examples/python)
- [OpenAI adapter](https://github.com/bighub-io/bighub/tree/main/adapters/python/openai)
- [MCP server](https://github.com/bighub-io/bighub/tree/main/servers/mcp)
- [PyPI - bighub](https://pypi.org/project/bighub/)
- [PyPI - bighub-openai](https://pypi.org/project/bighub-openai/)

---

## License

MIT
