Metadata-Version: 2.4
Name: sparkient-edge
Version: 0.1.0
Summary: Sub-10ms local decisions from Sparkient edge bundles — zero cloud dependencies
Project-URL: Homepage, https://sparkient.ai
Project-URL: Documentation, https://docs.sparkient.ai/edge
Project-URL: Changelog, https://github.com/sparkient/sparkient-edge/releases
Author-email: Sparkient <hello@sparkient.ai>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai,decisions,edge,inference,onnx,sparkient
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software 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: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: numpy>=2.1
Requires-Dist: onnxruntime>=1.20
Provides-Extra: all
Requires-Dist: cel-expr-python>=0.1; extra == 'all'
Requires-Dist: mcp>=1.27; extra == 'all'
Requires-Dist: model2vec>=0.4; extra == 'all'
Provides-Extra: mcp
Requires-Dist: mcp>=1.27; extra == 'mcp'
Provides-Extra: rules
Requires-Dist: cel-expr-python>=0.1; extra == 'rules'
Provides-Extra: text
Requires-Dist: model2vec>=0.4; extra == 'text'
Description-Content-Type: text/markdown

# sparkient-edge

**Sub-10ms local decisions from Sparkient edge bundles — zero cloud dependencies.**

Train your decision model on [Sparkient](https://sparkient.ai), export an edge bundle, and run predictions locally with no network, no database, and no API calls.

## Quick Start

```bash
pip install sparkient-edge
```

```python
from sparkient_edge import EdgePredictor

# Load a bundle exported from the Sparkient dashboard or API
predictor = EdgePredictor.from_bundle("my_decision_type.zip")

# Make a local decision — sub-10ms, no network
result = predictor.predict({
    "amount": 750,
    "account_age_days": 45,
    "risk_score": 0.55,
})

print(result.decision)            # "review"
print(result.confidence)          # 0.9985
print(result.stage)               # "classifier"
print(result.class_probabilities) # {"approve": 0.0006, "review": 0.9985, "block": 0.0009}
```

## How It Works

1. **Export** an edge bundle from Sparkient (dashboard or `GET /api/v1/decision-types/{id}/export`)
2. **Load** the bundle with `EdgePredictor.from_bundle("path/to/bundle.zip")`
3. **Predict** with `predictor.predict(your_input)` — runs CEL rules then ONNX classifier locally

The bundle contains everything needed: an ONNX model, feature configuration, CEL rules, and metadata. Typical bundle size is 1–10 KB.

## Optional Dependencies

The base install includes only `onnxruntime` and `numpy`. Install extras for additional features:

```bash
pip install sparkient-edge[all]    # Everything
pip install sparkient-edge[rules]  # CEL rule evaluation
pip install sparkient-edge[text]   # Text field embeddings (model2vec)
pip install sparkient-edge[mcp]    # MCP server support
```

| Extra | Adds | When needed |
|:------|:-----|:------------|
| `rules` | `cel-expr-python` | Decision types with CEL hard rules |
| `text` | `model2vec` | Decision types with free-text input fields |
| `mcp` | `mcp` | Running as a local MCP server |
| `all` | All of the above | Recommended for full functionality |

## MCP Server

Run as a local [Model Context Protocol](https://modelcontextprotocol.io) server for AI assistant integration:

```bash
sparkient-edge                    # Uses the CLI entry point
python -m sparkient_edge          # Or run as a module
```

Add to your MCP client config (Claude Desktop, Cursor, etc.):

```json
{
  "mcpServers": {
    "sparkient-edge": {
      "command": "sparkient-edge",
      "args": []
    }
  }
}
```

## EdgeDecision Fields

| Field | Type | Description |
|:------|:-----|:------------|
| `decision` | `str` | The chosen outcome (e.g., `"approve"`) |
| `confidence` | `float` | Confidence score (0.0 to 1.0) |
| `reason_codes` | `list[str]` | Why this decision was made |
| `stage` | `str` | Which stage decided: `"rules"`, `"classifier"`, or `"fallback"` |
| `class_probabilities` | `dict[str, float]` | Probability for each option |
| `rules_triggered` | `list[str]` | Names of rules that fired |

## Links

- [Documentation](https://docs.sparkient.ai/edge)
- [Sparkient Platform](https://sparkient.ai)
- [API Reference](https://docs.sparkient.ai/api)
