Skip to main content
Hivenora
Sign inGet Started

SDK Reference

SDK Reference

Hivenora provides SDK packages for Python and TypeScript. Both are framework-agnostic and have no LLM dependencies. Both are currently in private preview.

Private Preview. These packages are not yet published to npm or PyPI. Contact us for access to the preview builds, or call the REST API directly.

Installation

Python
TypeScript
bash
# Python 3.8+
pip install hivenora

# No required dependencies.
# Optional:
pip install hivenora[httpx]      # async support via httpx
pip install hivenora[anthropic]  # wrap() helper for Anthropic clients

Client initialization

Python
TypeScript
python
from hivenora import HivenoraClient

# API key from environment (recommended)
hivenora = HivenoraClient()

# Or pass explicitly
hivenora = HivenoraClient(
    api_key="hvn_test_example_never_use_real",
    base_url="https://api.hivenora.com",  # default
    timeout=10.0,   # seconds, default 10
    max_retries=2,  # default 2
)

evaluate()

The primary method. Submits a proposed action and returns a decision.

Parameters

actionREQUIRED
str | string
The action identifier. Use dot notation: crm.delete_contacts, stripe.refund, gmail.bulk_send.
intent
str | string
Natural language description of what the user asked the agent to do. Used for intent mismatch detection.
resource
str | string
Identifier for the primary resource being acted on.
context
dict | object
Structured metadata: records_affected, amount, environment, data_sensitivity, reversibility, recipients.
environment
"production" | "sandbox"
Overrides the environment in context if provided.
idempotency_key
str | string
If provided, duplicate calls with the same key return the cached decision for 5 minutes.

Return value

request_id
str
UUID identifying this evaluation. Use for approval polling.
decision
"allow" | "require_approval" | "block"
The policy decision.
effective_decision
"allow" | "require_approval" | "block"
The decision actually applied. In Shadow Mode, always "allow".
shadow_mode
bool
True when the agent is in Shadow Mode.
blast_radius
"critical" | "high" | "medium" | "low"
Estimated impact level.
blast_radius_factors
list[str]
Human-readable reasons for the blast radius classification.
intent_mismatch
bool
True if action scope appears to exceed stated intent.
reasons
list[str]
Reasons for the decision.
matched_policy
PolicyInfo | null
The policy that produced the decision, if any.
safer_alternative
SaferAlternative | null
A lower-impact alternative action suggested by Hivenora.
is_allowed
bool
Convenience: effective_decision === "allow".
requires_approval
bool
Convenience: effective_decision === "require_approval".
is_blocked
bool
Convenience: effective_decision === "block".

Async support

Python async
TypeScript (always async)
python
# Requires: pip install hivenora[httpx]
result = await hivenora.evaluate_async(
    action="crm.delete_contacts",
    context={"records_affected": 4821},
)

# Without httpx installed, evaluate_async() falls back
# to a thread pool executor (stdlib urllib).

Error handling

Python
TypeScript
python
from hivenora import (
    HivenoraError,         # base class
    HivenoraAuthError,     # 401/403 — bad API key
    HivenoraApiError,      # 4xx/5xx — e.attrs: status_code, body
    HivenoraNetworkError,  # network failure — e.cause
    HivenoraTimeoutError,  # extends NetworkError
)

try:
    result = hivenora.evaluate(action="...", ...)
except HivenoraAuthError:
    # Rotate the API key
    pass
except HivenoraNetworkError:
    # Fail closed — do not proceed
    raise RuntimeError("Cannot evaluate: Hivenora unreachable")
except HivenoraApiError as e:
    print(f"API error {e.status_code}: {e.body}")

Idempotency

Pass an idempotency_key to ensure that duplicate requests within a 5-minute window return the cached response instead of creating a new evaluation:

Python
TypeScript
python
result = hivenora.evaluate(
    action="stripe.refund",
    context={"amount": 8400},
    idempotency_key=f"refund-{order_id}-{attempt}",
)

The cache key is scoped to the agent. The same idempotency key submitted by a different agent produces a different cache entry.

REST API

You can call the API directly without the SDK:

bash
POST https://api.hivenora.com/v1/evaluate
X-Api-Key: hvn_test_example_never_use_real
Content-Type: application/json

{
  "action": "crm.delete_contacts",
  "intent": "Clean old test contacts",
  "context": {
    "records_affected": 4821,
    "environment": "production"
  }
}
← QuickstartShadow Mode →