Metadata-Version: 2.4
Name: loopgrid
Version: 0.1.0
Summary: Control plane for AI decision reliability. Capture, replay, and learn from AI decisions.
Project-URL: Homepage, https://github.com/cybertechsoft/loopgrid
Project-URL: Documentation, https://github.com/cybertechsoft/loopgrid#readme
Project-URL: Repository, https://github.com/cybertechsoft/loopgrid
Project-URL: Issues, https://github.com/cybertechsoft/loopgrid/issues
Project-URL: Changelog, https://github.com/cybertechsoft/loopgrid/releases
Author-email: Cybertech <hello@loopgrid.dev>
Maintainer-email: Cybertech <hello@loopgrid.dev>
License: Apache-2.0
License-File: LICENSE
Keywords: ai,ai-debugging,ai-reliability,anthropic,debugging,decision-ledger,decisions,infrastructure,llm,llm-ops,machine-learning,mlops,observability,openai,replay
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Requires-Dist: requests>=2.25.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: types-requests>=2.25.0; extra == 'dev'
Description-Content-Type: text/markdown

# LoopGrid

**The control plane for AI decision reliability.**

A system of record for AI decisions. Capture every decision immutably, replay failures with controlled overrides, and build ground truth from human corrections.

[![PyPI version](https://img.shields.io/pypi/v/loopgrid.svg)](https://pypi.org/project/loopgrid/)
[![Python versions](https://img.shields.io/pypi/pyversions/loopgrid.svg)](https://pypi.org/project/loopgrid/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

## Installation

```bash
pip install loopgrid
```

## Quick Start

```python
from loopgrid import LoopGrid

grid = LoopGrid(service_name="support-agent")

# Record an AI decision
decision = grid.record_decision(
    decision_type="customer_support_reply",
    input={"message": "I was charged twice"},
    model={"provider": "openai", "name": "gpt-4"},
    output={"response": "Your account looks fine."}
)

# Mark as incorrect
grid.mark_incorrect(decision["decision_id"], reason="Missed billing issue")

# Replay with different prompt
replay = grid.create_replay(
    decision_id=decision["decision_id"],
    overrides={"prompt": {"template": "support_v2"}}
)

# Attach human correction
grid.attach_correction(
    decision_id=decision["decision_id"],
    correction={"response": "Refund initiated."},
    corrected_by="agent_42"
)
```

## API Reference

### Constructor

```python
grid = LoopGrid(
    base_url="http://localhost:8000",  # LoopGrid server URL
    service_name="my-service",          # Your service name
    timeout=30                          # Request timeout (seconds)
)
```

### Decision Methods

| Method | Description |
|--------|-------------|
| `record_decision(...)` | Record an AI decision to the ledger |
| `get_decision(decision_id)` | Get a decision by ID |
| `list_decisions(...)` | List decisions with filters |
| `mark_incorrect(decision_id, reason)` | Mark a decision as incorrect |
| `attach_correction(...)` | Attach human correction |

### Replay Methods

| Method | Description |
|--------|-------------|
| `create_replay(...)` | Create a replay with overrides |
| `get_replay(replay_id)` | Get a replay by ID |
| `compare(decision_id, replay_id)` | Compare decision vs replay |

### Utility Methods

| Method | Description |
|--------|-------------|
| `health()` | Check server health |
| `info()` | Get server info |

## Type Hints

Full type hints are included (PEP 561 compliant):

```python
from loopgrid import LoopGrid

grid = LoopGrid(service_name="my-service")

decision = grid.record_decision(
    decision_type="support_reply",
    input={"message": "Help me"},
    model={"provider": "openai", "name": "gpt-4"},
    output={"response": "Sure!"}
)
```

## Server Setup

The SDK requires a LoopGrid server. See the [main repository](https://github.com/cybertechsoft/loopgrid) for server setup instructions.

```bash
# Quick start
git clone https://github.com/cybertechsoft/loopgrid.git
cd loopgrid
pip install -r requirements.txt
python run_server.py
```

## License

Apache 2.0 — see [LICENSE](LICENSE)

## Links

- [GitHub Repository](https://github.com/cybertechsoft/loopgrid)
- [PyPI Package](https://pypi.org/project/loopgrid/)
- [JavaScript SDK](https://www.npmjs.com/package/@cybertechsoft/loopgrid)
