Metadata-Version: 2.4
Name: niyati-core
Version: 0.3.5
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
License-File: LICENSE
Summary: Python SDK for Niyati, the hosted engine for reachability, fragility, and collapse-aware decision intelligence
Keywords: niyati,decision intelligence,simulation,reachability,strategy,fragility
Author-email: Nischay Tiwari <nischay@causalorlabs.com>
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://docs.causalorlabs.com
Project-URL: Issues, https://github.com/CausalorLabs/Niyati/issues
Project-URL: Repository, https://github.com/CausalorLabs/Niyati

# niyati-core

Python SDK for **Niyati**, the hosted engine for:

- reachable-future analysis
- collapse and fragility detection
- point-of-no-return tracking
- decision support under resource and timing constraints

Niyati is for cases where probability forecasts are not enough and you need to know what remains structurally possible.

Typical use cases:

- startup runway and survival planning
- prediction market and scenario elimination
- game decision validation and scoring
- strategic planning under budget, constraint, and path dependence

## Install

Published package flow:

```bash
pip install niyati-core
```

Local development flow:

```bash
pip install maturin
maturin develop
```

## Build

```bash
maturin build --release
```

Python `3.8` through `3.13` are supported directly. Python `3.14+` requires `PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1`.

## Hosted API

Default production API:

- `https://api.causalorlabs.com`

The current Python release line targets the live hosted API contract and sends the required version header automatically.

## Usage

```python
import json
import niyati

schema = {
    "version": "1.0.0",
    "metadata": {"name": "SDK Demo"},
    "time": {"type": "discrete", "horizon": 4},
    "resources": {
        "money": {"initial": 1000.0, "min": 0.0, "max": 10000.0}
    },
    "variables": {
        "x": {
            "type": "float",
            "initial": 0.0,
            "min": 0.0,
            "max": 10.0,
            "discretization": 1.0
        }
    },
    "actions": [
        {
            "name": "increment",
            "cost": {"money": 10.0},
            "effects": {"x": {"op": "add", "value": 1.0}},
            "preconditions": []
        }
    ],
    "transitions": [],
    "constraints": [],
    "goal": {
        "type": "threshold",
        "conditions": [{"variable": "x", "operator": "gte", "value": 3.0}]
    }
}

session = niyati.NiyatiSession(
    json.dumps(schema),
    api_key="your_api_key_here",
    base_url="https://api.causalorlabs.com"
)

remote_result = json.loads(session.evaluate())
local_result = json.loads(session.simulate_local())
```

## What You Get Back

Responses include:

- `verdict`
- `timeline`
- `point_of_no_return`
- `recommendation`
- `trust_level`
- `error_bounds`

That means the SDK is not just returning a binary answer; it gives you enough structure to build operator dashboards, game loops, alerts, and scenario tooling.

## Functions

- `simulate(schema_json, budget=None, api_key=None, base_url=None, capability=None)` - one-off remote evaluation (`capability`: `full` or `lite`, default `full`)
- `simulate_local(schema_json, budget=None)` - one-off local engine execution
- `NiyatiSession.evaluate(budget=None, capability=None)` - remote evaluation with timeout and retries
- `NiyatiSession.simulate_local(budget=None)` - capped local execution
- `NiyatiSession.solve_reachability(payload_json)` - calls `/v1/solve/reachability`
- `NiyatiSession.solve_fragility(payload_json)` - calls `/v1/solve/fragility`
- `NiyatiSession.solve_trajectory(payload_json)` - calls `/v1/solve/trajectory`
- `NiyatiSession.solve_multiagent(payload_json)` - calls `/v1/solve/multiagent`
- `NiyatiSession.solve_competition(payload_json)` - calls `/v1/solve/competition`
- `NiyatiSession.solve_pareto(payload_json)` - calls `/v1/solve/pareto`

## Runtime Notes

- Remote calls send the version header required by the hosted API.
- Retry attempts preserve `X-Niyati-Key`.
- `POST /v1/simulate` can be used anonymously, but `/v1/solve/*` requires a valid API key.
- Legacy class alias `CausalorSession` remains available during migration.
- Local execution is capped to `<= 5` variables and horizon `<= 12`.
- The production hosted API for Niyati is expected at `https://api.causalorlabs.com`.

## Learn More

- GitHub: `https://github.com/CausalorLabs/Niyati`
- API onboarding: `niyati-core/docs/API_ONBOARDING.md`
- Developer guide: `niyati-core/docs/DEVELOPER_GUIDE.md`

