blankstate-sdk 0.1.2

Python client for the Blankstate IBF API

blankstate-sdk

Python client for the Blankstate API (import package blankstate_sdk; PyPI distribution blankstate-sdk).

Measure interactions against behavioral protocols — get a score, per-metamarker resonance, signal analysis, and fidelity assessment. The engine runs server-side; this package handles auth, request formatting, and typed responses.

Install

pip install blankstate-sdk

Requires Python >= 3.10. Uses httpx for async HTTP and pydantic for typed responses.

---

Quick Start

import asyncio
from blankstate_sdk import Blankstate

bks = Blankstate(token="your_api_token")

async def main():
    result = await bks.sense("proto-xxx:1.0", "The agent resolved the issue promptly.")

    print(result.score)             # 0.82
    print(result.resonance)         # {"Solution-Oriented": 0.96, "Empathy": 0.41}
    print(result.fidelity)          # index=0.74 sufficient=True
    print(result.ics.consumed)      # 2

asyncio.run(main())

Or set your token via environment variable:

macOS / Linux:

export BLANKSTATE_API_TOKEN=bks_your_token

Windows:

$env:BLANKSTATE_API_TOKEN = "bks_your_token"

import os
from blankstate_sdk import Blankstate

bks = Blankstate(token=os.environ["BLANKSTATE_API_TOKEN"])

---

API

Blankstate(token, *, api_url=..., user_agent=...)

Parameter	Type	Default	Description
token	str | BlankstateOptions	—	API token (required), or pass BlankstateOptions as the only positional argument
api_url	str	https://ibf.blankstate.ai	API base URL
user_agent	str	blankstate-sdk	User-Agent header sent with every request (including healthy())

Equivalent to the JS options object:

from blankstate_sdk import Blankstate, BlankstateOptions

bks = Blankstate(BlankstateOptions(token="...", api_url="https://ibf.blankstate.ai"))

Response models live in blankstate_sdk.models (import types from there for annotations).

---

Sense

Measure content against a protocol. The measurement engine version is set by the protocol definition — not by the caller.

result = await bks.sense(
    "proto-xxx:1.0",
    content,
    language="en",          # default: "en"
    profile="detailed",     # "raw" | "detailed" | "discovery"
    depth="full",           # "measure" | "full"
)

result.score          # overall alignment (0.0–1.0)
result.resonance      # {"Empathy": 0.91, "Solution-Oriented": 0.76}
result.signal         # spread, coherence, dominant_mode (v1.5 protocols)
result.actant_flow    # entity influence direction (v1.5 protocols)
result.temporal       # temporal trend analysis (v1.5 protocols)
result.fidelity       # index, sufficient
result.ics            # consumed, cost_usd, sgm_version, pool

Measure against multiple protocols in parallel:

results = await bks.sense_multiple(
    ["proto-aaa:1.0", "proto-bbb:2.0"],
    content,
)
# returns dict[protocol_id, SenseResponse]
# failed protocols are silently dropped

---

Fidelity Check — 0 ICS

Pre-check whether content has enough signal for measurement before spending ICS:

check = await bks.fidelity_check("proto-xxx:1.0", content)

check.fidelity.sufficient     # True | False
check.fidelity.index          # 0.74
check.estimated_ics           # ICSRange(min=1, max=3, typical=2)

---

Status and Usage

status = await bks.status()
# status.authenticated
# status.sgm_versions       — {"1.0": "stable", "1.5": "extended"}
# status.ics.remaining
# status.ics.member         — member-level cap if set

usage = await bks.usage()
# usage.ics_used, usage.ics_remaining, usage.ics_total

estimate = await bks.usage_estimate(content_length=500, modality="text")
# estimate.estimated_ics, estimate.will_exceed_quota

---

Protocols

# List protocols in your account
protocols = await bks.protocols()
# [ProtocolSummary(id=..., name=..., versions=[...], sgm_version=...)]

# Get a protocol's full definition
definition = await bks.protocol("proto-xxx:1.0")
# definition.id, definition.name, definition.version, definition.sgm_version
# definition.metamarkers  — [ProtocolMetamarker(label=..., description=...)]
# definition.taxonomy, definition.supported_modalities

---

Health

ok = await bks.healthy()  # True | False — 0 ICS, no auth required

---

Error Handling

from blankstate_sdk import BlankstateAPIError

try:
    result = await bks.sense("proto-xxx:1.0", content)
except BlankstateAPIError as err:
    print(err.status_code)      # HTTP status code
    print(err.error_message)    # human-readable message
    print(err.code)             # machine-readable error code

    if err.is_auth_error():     # 401/403 — check your token
        ...
    if err.is_quota_error():    # 429 — ICS quota exceeded
        print(err.ics_info)     # {"quota": 50, "used": 50, "remaining": 0}
    if err.is_server_error():   # 5xx — retryable
        ...

---

Development

This package has its own pyproject.toml. From the repo root:

git clone https://github.com/blankstate-ai/blankstate-py.git
cd blankstate-py

python3 -m pip install -e "./packages/sdk[dev]"
pytest packages/sdk/tests

Or from packages/sdk/:

cd packages/sdk
pip install -e ".[dev]"
pytest

---

Concepts

Term	Description
Protocol	A behavioral sensor — defines metamarkers that characterize an interaction pattern
Metamarker	A named behavioral signal (e.g., "Empathy", "Escalation Risk")
Resonance	Activation strength of each metamarker (0.0–1.0)
Score	Aggregate alignment between content and the protocol
Fidelity	Signal quality — whether content has enough substance for reliable measurement
ICS	Interaction Computed Signal — billing unit per measurement
SGM	Blankstate measurement engine — v1.0 (stable), v1.5 (extended signal analysis)

---

Requirements

• Python >= 3.10
• API token from atlas.blankstate.ai

Links

• Atlas — Dashboard, API tokens, protocol management
• API Reference — Full REST API documentation
• Issues — Bug reports and feature requests

License

MIT — blankstate.ai