Skip to main content
Hivenora
Sign inGet Started

Quickstart

Get your first Hivenora decision running.

This guide walks you through creating an account, installing the SDK, and sending your first action evaluation. The current integration path uses the Hivenora REST API or the SDK packages in the private preview.

Private Preview. The Python and TypeScript SDK packages are not yet published to PyPI or npm. Contact us to get access to the private preview build, or call the REST API directly. Example credentials below are illustrative only — never use real API keys in code samples.

Step 1 — Create an account and API key

Open the Control Room and sign in. Navigate to Agents → New Agent and register your agent. Copy the API key shown once at creation — it will not be displayed again.

Set it as an environment variable in your application:

bash
export HIVENORA_API_KEY="hvn_test_example_key_never_use_real"

Keys have the prefix hvn_. Never commit keys to source control. Use environment variables or a secrets manager.

Step 2 — Install the SDK

Install the SDK for your language. Both are currently in private preview — contact us for access.

Python
TypeScript
bash
# Private preview — contact us for access
pip install hivenora

# Dependencies: none required
# Optional: pip install hivenora[httpx]  (for async support)
# Optional: pip install hivenora[anthropic]  (for wrap() helper)

Step 3 — Initialize the client

Python
TypeScript
python
from hivenora import HivenoraClient

hivenora = HivenoraClient(
    api_key="hvn_test_example_key_never_use_real"
    # Or: omit to read HIVENORA_API_KEY from environment
)

Step 4 — Evaluate an action

Before executing a consequential action, call evaluate()and handle the decision:

Python
TypeScript
python
result = hivenora.evaluate(
    action="crm.delete_contacts",
    intent="Clean old test contacts from Q1 2024",
    context={
        "records_affected": 4821,
        "environment": "production",
        "data_sensitivity": "customer_pii",
        "reversibility": "low",
    },
)

if result.is_allowed:
    delete_contacts()
elif result.requires_approval:
    print(f"Waiting for approval: {result.request_id}")
    # Poll /v1/approvals/{result.request_id} or use webhooks
else:
    raise RuntimeError(f"Blocked: {result.reasons[0]}")

The response for this example would be:

json
{
  "request_id": "01927a3b-e4f6-7abc-8def-123456789012",
  "decision": "require_approval",
  "effective_decision": "require_approval",
  "shadow_mode": false,
  "blast_radius": "critical",
  "blast_radius_factors": [
    "4,821 records affected",
    "317 active opportunities linked",
    "42 enterprise accounts affected",
    "Production environment"
  ],
  "intent_mismatch": true,
  "reasons": [
    "Blast radius classified CRITICAL — exceeds autonomous action threshold",
    "Action scope (4,821 records) exceeds intent scope"
  ],
  "matched_policy": {
    "id": "pol_abc123",
    "name": "Large Scope CRM Protection",
    "action": "require_approval"
  }
}

Step 5 — Open the Control Room

Open the Control Room and navigate to Activity. Your evaluation appears immediately. Click any row to open the Flight Recorder — the full evaluation trace showing intent analysis, impact factors, policy match, and decision chain.

If your action required approval, it appears in Approvals. An operator reviews the action details and clicks Approve or Deny. Your application can poll the approval status or receive a webhook.

Calling the API directly

You can also call the REST API directly without the SDK:

bash
curl -X POST https://api.hivenora.com/v1/evaluate \
  -H "X-Api-Key: hvn_test_example_key_never_use_real" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "crm.delete_contacts",
    "intent": "Clean old test contacts from Q1 2024",
    "context": {
      "records_affected": 4821,
      "environment": "production"
    }
  }'

Error handling

The SDK raises typed exceptions for all error conditions:

Python
TypeScript
python
from hivenora import (
    HivenoraAuthError,     # 401/403 — bad or missing API key
    HivenoraApiError,      # 4xx/5xx — API returned an error
    HivenoraNetworkError,  # Network failure — could not reach API
    HivenoraTimeoutError,  # Request exceeded timeout
)

try:
    result = hivenora.evaluate(action="crm.delete_contacts", ...)
except HivenoraAuthError:
    # Invalid API key — check HIVENORA_API_KEY
    raise
except HivenoraNetworkError:
    # Network issue — Hivenora uses fail-closed behavior
    # Treat as blocked until connectivity is restored
    raise RuntimeError("Cannot evaluate action: Hivenora unreachable")
Fail-closed behavior. On network errors, the SDK throws rather than returning a default decision. Your application is responsible for deciding how to handle unreachable Hivenora — the recommended default is to treat it as blocked and not proceed with the action.
← IntroductionCore Concepts →