niyati-core 0.3.5

Python SDK for Niyati, the hosted engine for reachability, fragility, and collapse-aware decision intelligence

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:

pip install niyati-core

Local development flow:

pip install maturin
maturin develop

Build

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

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