manage-ai-sdk 0.4.0

Lightweight SDK for pushing automation run logs to the Manage AI dashboard

Manage AI SDK

Lightweight Python SDK for pushing automation run logs to the Manage AI dashboard.

Install

pip install manage-ai-sdk
# or directly from the repo
pip install "manage-ai-sdk @ git+https://github.com/Shfa-AI/manage-ai.git#subdirectory=sdk"

Setup

Set two environment variables (or pass them explicitly):

export MANAGE_AI_URL=https://your-dashboard.example.com
export MANAGE_AI_KEY=ak_your_api_key_here

Get these from the Connection section on any automation's detail page in the dashboard.

Usage

Decorator (simplest)

from manage_ai_sdk import automation

@automation("b1000000-0000-0000-0000-000000000001")
def daily_invoice_email():
    invoices = fetch_invoices()
    send_emails(invoices)
    return {"invoices_sent": len(invoices)}

if __name__ == "__main__":
    daily_invoice_email()

The decorator automatically:

• Reports the run as started when the function begins
• Reports success with the return value as output when it finishes
• Reports failure with the traceback if an exception occurs
• Tracks duration

Analytics events (SEO-style automation metrics)

Use canonical events so analytics works consistently across repositories.

from manage_ai_sdk import ManageAI

client = ManageAI()
automation_id = "b1000000-0000-0000-0000-000000000001"
session_id = "sess_123"
user_id = "user_42"

client.track_event(
    automation_id,
    "user_logged_in",
    actor_user_id=user_id,
    session_id=session_id,
    channel="web",
)

client.track_event(
    automation_id,
    "question_asked",
    actor_user_id=user_id,
    session_id=session_id,
    question_id="q_001",
    question_text_raw="Can I export this report as CSV?",
    question_category="reporting",
)

client.track_event(
    automation_id,
    "answer_returned",
    actor_user_id=user_id,
    session_id=session_id,
    question_id="q_001",
    answer_id="a_001",
    answer_text_raw="Yes. Open Reports -> Export -> CSV.",
    answer_source="rag",
)

Supported canonical event names:

• user_logged_in
• automation_opened
• session_started
• question_asked
• answer_returned
• cta_clicked
• session_resolved
• session_unresolved
• session_ended

SDK freeze policy (schema v1)

The analytics event contract is versioned and stable at schema_version=1.

• Safe changes: add optional fields, add new events with fallback handling.
• Breaking changes: rename/remove event names or required fields.
• Breaking changes require a new schema version.

Context manager (for embedding in existing code)

from manage_ai_sdk import track_run

with track_run("b1000000-0000-0000-0000-000000000001") as run:
    result = do_stuff()
    run.output = {"data": result}

Explicit client (for advanced usage)

from manage_ai_sdk import ManageAI

client = ManageAI(url="https://...", api_key="ak_...")
run_id = client.start_run("b1000000-...", trigger={"type": "cron"})

try:
    result = do_stuff()
    client.complete_run("b1000000-...", run_id, output={"data": result}, duration_ms=1234)
except Exception as e:
    client.fail_run("b1000000-...", run_id, error=str(e))
    raise

Live connection heartbeat bridge

Use a background bridge for long-running workers so the dashboard can show real-time connection status.

import time
from manage_ai_sdk import ManageAI

client = ManageAI()
automation_id = "b1000000-0000-0000-0000-000000000001"
bridge = client.start_heartbeat_bridge(automation_id, interval_seconds=60)

try:
    while True:
        # your worker loop
        time.sleep(10)
finally:
    bridge.stop()

Notes:

• start_run and track_event also send a one-off heartbeat.
• For always-on processes, prefer start_heartbeat_bridge so status stays fresh while idle.
• Heartbeat retries transient failures with exponential backoff + jitter.

Configuration priority

1. Explicit arguments — automation("id", url="...", api_key="...")
2. Environment variables — MANAGE_AI_URL, MANAGE_AI_KEY

Failure behavior

If the dashboard is unreachable, the SDK logs a warning but does not crash your automation. Your code always runs regardless of whether the dashboard is available.