farol-sdk 0.1.0__tar.gz

farol_sdk-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.env
+config.js
+venv/
+__pycache__/
+*.pyc
+runs.json

farol_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: farol-sdk
+Version: 0.1.0
+Summary: Agent observability for builders
+Project-URL: Homepage, https://usefarol.dev
+Author: Farol
+License: MIT
+Keywords: agents,llm,observability,supabase,tracing
+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.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Provides-Extra: all
+Requires-Dist: resend>=2.0.0; extra == 'all'
+Requires-Dist: supabase>=2.0.0; extra == 'all'
+Provides-Extra: resend
+Requires-Dist: resend>=2.0.0; extra == 'resend'
+Provides-Extra: supabase
+Requires-Dist: supabase>=2.0.0; extra == 'supabase'
+Description-Content-Type: text/markdown
+
+# farol-sdk
+
+Agent observability for builders. Wrap a function with `@trace`, pass token counts on the `run` dict, and Farol syncs runs to your dashboard—cost anomalies, alerts, the lot.
+
+**[usefarol.dev](https://usefarol.dev)**
+
+---
+
+## Install
+
+```bash
+pip install farol-sdk
+```
+
+Sync to Supabase and email alerts need extras (zero required deps otherwise):
+
+```bash
+pip install 'farol-sdk[supabase,resend]'
+```
+
+Set environment variables: `SUPABASE_URL`, `SUPABASE_KEY`, optionally `SUPABASE_SERVICE_KEY` for writes + API key resolution; `RESEND_API_KEY` and `ALERT_EMAIL` for anomaly emails.
+
+---
+
+## Usage
+
+```python
+from farol import trace
+
+@trace("research-agent", farol_key="frl_your_key_here", model="claude-3-5-haiku-latest")
+def my_agent(task: str, *, run):
+    run["input_tokens"] = 100
+    run["output_tokens"] = 50
+    return "done"
+```
+
+The wrapped function receives `run` with `steps`, token fields, and timing; Farol computes cost from `cost_per_1k_tokens` (default suits many providers—override as needed).
+
+---
+
+## License
+
+MIT

farol_sdk-0.1.0/README.md

@@ -0,0 +1,43 @@
+# farol-sdk
+
+Agent observability for builders. Wrap a function with `@trace`, pass token counts on the `run` dict, and Farol syncs runs to your dashboard—cost anomalies, alerts, the lot.
+
+**[usefarol.dev](https://usefarol.dev)**
+
+---
+
+## Install
+
+```bash
+pip install farol-sdk
+```
+
+Sync to Supabase and email alerts need extras (zero required deps otherwise):
+
+```bash
+pip install 'farol-sdk[supabase,resend]'
+```
+
+Set environment variables: `SUPABASE_URL`, `SUPABASE_KEY`, optionally `SUPABASE_SERVICE_KEY` for writes + API key resolution; `RESEND_API_KEY` and `ALERT_EMAIL` for anomaly emails.
+
+---
+
+## Usage
+
+```python
+from farol import trace
+
+@trace("research-agent", farol_key="frl_your_key_here", model="claude-3-5-haiku-latest")
+def my_agent(task: str, *, run):
+    run["input_tokens"] = 100
+    run["output_tokens"] = 50
+    return "done"
+```
+
+The wrapped function receives `run` with `steps`, token fields, and timing; Farol computes cost from `cost_per_1k_tokens` (default suits many providers—override as needed).
+
+---
+
+## License
+
+MIT

farol_sdk-0.1.0/farol/__init__.py

@@ -0,0 +1,7 @@
+"""Farol — agent observability for builders."""
+
+from farol.sdk import trace
+
+__version__ = "0.1.0"
+
+__all__ = ["trace", "__version__"]

farol_sdk-0.1.0/farol/sdk.py

@@ -0,0 +1,265 @@
+"""
+Farol SDK — trace decorator and run sync.
+
+Optional integrations (install extras: pip install 'farol-sdk[supabase]' etc.):
+  - supabase: sync runs, baseline lookup for anomaly detection
+  - resend: email alerts on cost anomalies
+
+Environment variables (when using integrations):
+  SUPABASE_URL, SUPABASE_KEY — read baseline / optional anon client
+  SUPABASE_SERVICE_KEY — if set, used for api_keys lookup and runs insert (recommended)
+  RESEND_API_KEY, ALERT_EMAIL — anomaly emails
+"""
+
+from __future__ import annotations
+
+import os
+import statistics
+import time
+from datetime import datetime
+from typing import Any, Callable, Optional, TypeVar
+
+COST_ALERT_THRESHOLD = 0.0001
+
+try:
+    from supabase import create_client as _create_client
+except ImportError:  # pragma: no cover
+    _create_client = None  # type: ignore[misc, assignment]
+
+try:
+    import resend as _resend
+except ImportError:  # pragma: no cover
+    _resend = None
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+_supabase_read = None
+_supabase_admin = None
+_clients_initialized = False
+
+
+def _init_supabase_clients() -> None:
+    global _supabase_read, _supabase_admin, _clients_initialized
+    if _clients_initialized:
+        return
+    _clients_initialized = True
+    if _create_client is None:
+        return
+    url = os.environ.get("SUPABASE_URL")
+    key = os.environ.get("SUPABASE_KEY")
+    service = os.environ.get("SUPABASE_SERVICE_KEY")
+    if not url or not key:
+        return
+    try:
+        _supabase_read = _create_client(url, key)
+        _supabase_admin = _create_client(url, service) if service else _supabase_read
+    except Exception:  # pragma: no cover
+        _supabase_read = None
+        _supabase_admin = None
+
+
+def _supabase_ready() -> bool:
+    _init_supabase_clients()
+    return _supabase_read is not None and _supabase_admin is not None
+
+
+def _finalize_run_logging(run: dict) -> None:
+    print(
+        f"[Farol] Run recorded — {run['duration_ms']}ms | ${run['cost_usd']} | "
+        f"status: {run['status']}"
+    )
+    if run["cost_usd"] > COST_ALERT_THRESHOLD:
+        print(
+            f"[Farol] COST ALERT — {run['agent']} exceeded ${COST_ALERT_THRESHOLD} "
+            f"threshold (actual: ${run['cost_usd']})"
+        )
+    if run["anomaly"]:
+        print(f"[Farol] COST ANOMALY DETECTED — {run['anomaly_reason']}")
+        _send_anomaly_email(run)
+
+
+def _send_anomaly_email(run: dict) -> None:
+    if _resend is None:
+        return
+    api_key = os.environ.get("RESEND_API_KEY")
+    alert_to = os.environ.get("ALERT_EMAIL")
+    if not api_key or not alert_to:
+        return
+    _resend.api_key = api_key
+    email_payload = {
+        "to": [alert_to],
+        "subject": f"[Farol] Cost anomaly detected — {run['agent']}",
+        "text": (
+            "A cost anomaly was detected by Farol.\n\n"
+            f"Agent: {run['agent']}\n"
+            f"Reason: {run.get('anomaly_reason')}\n"
+            f"Run ID: {run['id']}\n"
+            f"Timestamp: {run['timestamp']}\n"
+        ),
+    }
+    try:
+        _resend.Emails.send({**email_payload, "from": "Farol <alerts@usefarol.dev>"})
+    except Exception:
+        try:
+            _resend.Emails.send({**email_payload, "from": "Farol <onboarding@resend.dev>"})
+        except Exception:
+            pass
+
+
+def save_run(run: dict) -> None:
+    anomaly = False
+    anomaly_reason: Optional[str] = None
+
+    if _supabase_ready() and _supabase_read is not None:
+        try:
+            baseline_response = (
+                _supabase_read.table("runs")
+                .select("cost_usd")
+                .eq("agent", run["agent"])
+                .eq("status", "success")
+                .order("timestamp", desc=True)
+                .limit(20)
+                .execute()
+            )
+            baseline_rows = baseline_response.data or []
+        except Exception as e:
+            print(f"[Farol] Baseline lookup failed: {e}")
+            baseline_rows = []
+    else:
+        baseline_rows = []
+
+    baseline_costs = []
+    for row in baseline_rows:
+        try:
+            baseline_costs.append(float(row.get("cost_usd")))
+        except (TypeError, ValueError, AttributeError):
+            continue
+
+    if len(baseline_costs) < 5:
+        anomaly = False
+        anomaly_reason = "Building baseline — need 5+ runs"
+    else:
+        median_cost = statistics.median(baseline_costs)
+        mean_cost = statistics.mean(baseline_costs)
+        std_dev_cost = statistics.stdev(baseline_costs)
+        current_cost = float(run["cost_usd"])
+
+        is_over_3x_median = current_cost > (3 * median_cost)
+        is_over_2x_and_2std = current_cost > (2 * median_cost) and current_cost > (
+            mean_cost + (2 * std_dev_cost)
+        )
+
+        if is_over_3x_median or is_over_2x_and_2std:
+            anomaly = True
+            ratio = (current_cost / median_cost) if median_cost > 0 else float("inf")
+            ratio_text = "∞" if ratio == float("inf") else f"{ratio:.1f}"
+            anomaly_reason = (
+                f"Cost {ratio_text}× above median baseline "
+                f"(median: ${median_cost:.6f}, actual: ${current_cost:.6f})"
+            )
+        else:
+            anomaly = False
+            anomaly_reason = None
+
+    run["anomaly"] = anomaly
+    run["anomaly_reason"] = anomaly_reason
+
+    if not _supabase_ready() or _supabase_admin is None:
+        _finalize_run_logging(run)
+        return
+
+    try:
+        user_id = None
+        if run.get("farol_key"):
+            try:
+                key_res = (
+                    _supabase_admin.table("api_keys")
+                    .select("user_id")
+                    .eq("api_key", run["farol_key"])
+                    .limit(1)
+                    .execute()
+                )
+                key_rows = key_res.data or []
+                if key_rows and key_rows[0].get("user_id"):
+                    user_id = key_rows[0].get("user_id")
+                else:
+                    print("[Farol] Invalid API key — run not synced")
+                    return
+            except Exception:
+                print("[Farol] Invalid API key — run not synced")
+                return
+
+        payload = {
+            "id": run["id"],
+            "agent": run["agent"],
+            "model": run["model"],
+            "topic": run.get("topic"),
+            "status": run["status"],
+            "duration_ms": run["duration_ms"],
+            "input_tokens": run["input_tokens"],
+            "output_tokens": run["output_tokens"],
+            "cost_usd": float(run["cost_usd"]),
+            "anomaly": run.get("anomaly", False),
+            "anomaly_reason": run.get("anomaly_reason", None),
+            "steps": run["steps"],
+            "error": run.get("error"),
+            "timestamp": run["timestamp"],
+        }
+        if user_id is not None:
+            payload["user_id"] = user_id
+
+        _supabase_admin.table("runs").insert(payload).execute()
+        print("[Farol] Synced to Supabase")
+    except Exception as e:
+        print(f"[Farol] Supabase sync failed: {e}")
+
+    _finalize_run_logging(run)
+
+
+def trace(
+    agent_name: str,
+    farol_key: Optional[str] = None,
+    model: str = "claude-haiku-4-5-20251001",
+    cost_per_1k_tokens: float = 0.00025,
+) -> Callable[[F], F]:
+    def decorator(func: F) -> F:
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            run: dict[str, Any] = {
+                "id": f"run_{int(time.time())}",
+                "agent": agent_name,
+                "model": model,
+                "timestamp": datetime.utcnow().isoformat(),
+                "status": "running",
+                "steps": [],
+                "input_tokens": 0,
+                "output_tokens": 0,
+                "cost_usd": 0.0,
+                "duration_ms": 0,
+                "error": None,
+                "anomaly": False,
+                "anomaly_reason": None,
+            }
+            if farol_key:
+                run["farol_key"] = farol_key
+
+            start = time.time()
+
+            try:
+                result = func(*args, run=run, **kwargs)
+                run["status"] = "success"
+                return result
+            except Exception as e:
+                run["status"] = "error"
+                run["error"] = str(e)
+                raise
+            finally:
+                run["duration_ms"] = round((time.time() - start) * 1000)
+                run["cost_usd"] = round(
+                    (run["input_tokens"] + run["output_tokens"]) / 1000 * cost_per_1k_tokens,
+                    6,
+                )
+                save_run(run)
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator

farol_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling>=1.18.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "farol-sdk"
+version = "0.1.0"
+description = "Agent observability for builders"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+  { name = "Farol" },
+]
+keywords = ["observability", "agents", "llm", "tracing", "supabase"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+dependencies = []
+
+[project.optional-dependencies]
+supabase = ["supabase>=2.0.0"]
+resend = ["resend>=2.0.0"]
+all = ["supabase>=2.0.0", "resend>=2.0.0"]
+
+[project.urls]
+Homepage = "https://usefarol.dev"
+
+[tool.hatch.build.targets.wheel]
+packages = ["farol"]