Metadata-Version: 2.4
Name: manage-ai-sdk
Version: 0.4.0
Summary: Lightweight SDK for pushing automation run logs to the Manage AI dashboard
Project-URL: Homepage, https://github.com/Shfa-AI/manage-ai
Project-URL: Repository, https://github.com/Shfa-AI/manage-ai
Project-URL: Issues, https://github.com/Shfa-AI/manage-ai/issues
License-Expression: MIT
License-File: LICENSE
Keywords: automation,dashboard,monitoring,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Description-Content-Type: text/markdown

# Manage AI SDK

Lightweight Python SDK for pushing automation run logs to the [Manage AI](https://github.com/Shfa-AI/manage-ai) dashboard.

## Install

```bash
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):

```bash
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)

```python
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.

```python
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)

```python
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)

```python
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.

```python
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.
