Metadata-Version: 2.5
Name: sparkient-edge
Version: 0.5.0
Summary: Local decisions from Sparkient edge bundles without Sparkient API calls after download
Project-URL: Homepage, https://sparkient.ai
Project-URL: Documentation, https://docs.sparkient.ai/docs/edge/getting-started/
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
Requires-Dist: tokenizers>=0.15
Provides-Extra: all
Requires-Dist: cel-expr-python>=0.1; extra == 'all'
Requires-Dist: mcp<2,>=1.27; extra == 'all'
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.27; extra == 'mcp'
Provides-Extra: rules
Requires-Dist: cel-expr-python>=0.1; extra == 'rules'
Description-Content-Type: text/markdown

# sparkient-edge

**Local decisions from Sparkient edge bundles without a Sparkient API call after download.**

Train a decision model on [Sparkient](https://sparkient.ai), export an edge bundle, and run predictions in a compatible Python 3.10+ environment without a network call.

> **Status:** `sparkient-edge` is beta software. Benchmark the complete bundle on the target hardware before relying on its latency or capacity in production.

## Quick Start

```bash
pip install "sparkient-edge[all]"
```

```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 — no network; measure latency on target hardware
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 expression rules then compiled classifier locally

The bundle contains the compiled model, feature configuration, expression rules, metadata, and text-processing assets when applicable. Bundle size and local latency depend on the decision type, model, and target hardware.

## Optional Dependencies

The quick start installs every runtime feature so exported rules cannot be skipped. Use the minimal base install only for rule-free bundles when you do not need MCP:

```bash
pip install "sparkient-edge[all]"    # Everything; recommended
pip install "sparkient-edge[rules]"  # Expression rule evaluation
pip install "sparkient-edge[mcp]"    # MCP only; use only with rule-free bundles
```

| Extra | Adds | When needed |
|:------|:-----|:------------|
| `rules` | Rule engine | Decision types with expression-based hard rules |
| `mcp` | `mcp` | Running as a local MCP server |
| `all` | Both optional features | Bundles with rules used through MCP |

The base package includes ONNX Runtime, NumPy, and the tokenizer needed by exported text models. Compatible wheels must exist for the target Python version, operating system, and architecture.

## MCP Server

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

```bash
pip install "sparkient-edge[all]"
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 |

## Limits

- The package runs exported rules and classifiers only. It does not use Sparkient's optional cloud LLM escalation.
- Bundle size, local latency, memory use, and throughput depend on the model and target hardware.
- Training, retraining, and bundle export still use the Sparkient service. Edge export is available on Growth and Scale plans.
- This Python package is not a native Android, iOS, microcontroller, or embedded-device SDK.
- Local compute and the applicable Sparkient plan still have a cost; offline inference is not the same as free inference.

## Links

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