sovara 0.3.2__tar.gz → 0.3.4__tar.gz

sovara-0.3.4/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: sovara
+Version: 0.3.4
+Summary: Python SDK for Sovara agent observability and runtime instrumentation
+Project-URL: Documentation, https://docs.sovara-labs.com
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: dill
+Requires-Dist: flatten_dict
+Requires-Dist: flatten_json
+Requires-Dist: httpx
+Requires-Dist: jsonpickle>=4.1.1
+Requires-Dist: keyring>=25.0.0
+Requires-Dist: pydantic
+Requires-Dist: pyyaml
+Provides-Extra: examples
+Requires-Dist: openai; extra == "examples"
+Requires-Dist: anthropic; extra == "examples"
+Requires-Dist: openai-agents; extra == "examples"
+Requires-Dist: google-genai; extra == "examples"
+Requires-Dist: claude-agent-sdk; extra == "examples"
+
+# Sovara Python SDK
+
+The `sovara` package instruments Python agents so Sovara can record LLM calls,
+tool calls, logs, and custom trace spans.
+
+Install it in the Python environment where your agent runs:
+
+```bash
+python -m pip install sovara
+```
+
+Or with `uv`:
+
+```bash
+uv add sovara
+```
+
+Use `sovara.run(...)` for library-mode recording:
+
+```python
+import sovara
+
+with sovara.run("support-agent"):
+    run_agent()
+```
+
+The terminal command is distributed separately as the native Sovara CLI. Install
+that CLI for commands such as `sovara record`, `sovara status`, and
+`sovara probe`.
+
+Documentation: https://docs.sovara-labs.com

sovara-0.3.4/README.md

@@ -0,0 +1,31 @@
+# Sovara Python SDK
+
+The `sovara` package instruments Python agents so Sovara can record LLM calls,
+tool calls, logs, and custom trace spans.
+
+Install it in the Python environment where your agent runs:
+
+```bash
+python -m pip install sovara
+```
+
+Or with `uv`:
+
+```bash
+uv add sovara
+```
+
+Use `sovara.run(...)` for library-mode recording:
+
+```python
+import sovara
+
+with sovara.run("support-agent"):
+    run_agent()
+```
+
+The terminal command is distributed separately as the native Sovara CLI. Install
+that CLI for commands such as `sovara record`, `sovara status`, and
+`sovara probe`.
+
+Documentation: https://docs.sovara-labs.com

sovara-0.3.4/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.package-data]
+"sovara.assets" = ["sovara/*.md", "sovara/references/*.md", "sovara/evals/*.json"]
+"sovara.common" = ["*.json"]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["sovara*"]
+
+[project]
+name = "sovara"
+version = "0.3.4"
+description = "Python SDK for Sovara agent observability and runtime instrumentation"
+readme = "README.md"
+requires-python = ">=3.10"
+
+dependencies = [
+    "dill",
+    "flatten_dict",
+    "flatten_json",
+    "httpx",
+    "jsonpickle>=4.1.1",
+    "keyring>=25.0.0",
+    "pydantic",
+    "pyyaml",
+]
+
+[project.optional-dependencies]
+examples = [
+    "openai",
+    "anthropic",
+    "openai-agents",
+    "google-genai",
+    "claude-agent-sdk",
+]
+
+[project.urls]
+Documentation = "https://docs.sovara-labs.com"

{sovara-0.3.2 → sovara-0.3.4}/src/sovara/__init__.py

@@ -13,11 +13,13 @@ from sovara.runner.public import (
     queue_for_annotation_async,
     run,
 )
+from sovara.runner.trace import trace
 
 apply_all_monkey_patches()
 
 __all__ = [
     "run",
+    "trace",
     "annotate",
     "queue_for_annotation",
     "queue_for_annotation_async",

sovara-0.3.4/src/sovara/assets/sovara/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: sovara
+description: >
+  Use when a user wants to debug, observe, optimize, or capture lessons
+  from a Python or TypeScript LLM agent — recording runs as dataflow
+  graphs of LLM and tool calls, inspecting which step produced a wrong
+  answer, comparing runs to find regressions, annotating failures, or
+  turning recurring lessons into priors that are injected back into
+  context at runtime. Also covers installing the Sovara desktop app,
+  SDK, or CLI, deploying `sovara-server` on Azure with Microsoft
+  Entra auth, or configuring Sovara for Palantir Foundry. Trigger even when the user does not say "Sovara" —
+  phrases like "my agent keeps giving wrong answers", "trace this LLM
+  call", "the agent regressed after my last change", "remember this
+  rule for next time", "inject domain knowledge into my agent at
+  runtime", or "set up observability for my agent" all apply. Do not
+  use for generic prompt engineering with no run inspection, generic
+  HTTP/SQL tracing unrelated to LLM agents, or Azure deployment
+  unrelated to `sovara-server`.
+---
+
+# sovara
+
+## Overview
+
+Sovara helps develop and maintain adaptable agentic systems by recording traces as dataflow graphs and injecting learned priors at runtime.
+
+Core capabilities:
+
+- **Integrated observability**: Record agent traces as dataflow graphs with zero code changes for supported Python workflows.
+- **Priors**: Create, retrieve, validate, and inject reusable lessons into agent context.
+- **SDK install guidance**: Install the desktop app, SDK/runner, CLI, and assistant skill.
+- **Enterprise deploy guidance**: Stand up `sovara-server` on Azure with Microsoft Entra auth.
+- **Palantir setup guidance**: Configure Sovara to use Palantir Foundry as the storage backend and embedding provider.
+
+## Setup Gate
+
+Run project setup checks only for workflows that execute Sovara against a project: recording, probing, logs, annotations, priors, or connecting an agent to a server. Skip this gate when the user only needs SDK/CLI installation guidance or enterprise deployment planning.
+
+For project-scoped workflows:
+
+1. Run `sovara status --path <script-or-project-dir>` before the first project command.
+2. If setup is missing, run `sovara init --project-root <dir> --project-name "<name>"`.
+3. In non-interactive shells, do not rely on prompts. Initialize first, or pass `--project-root`, `--project-name`, and `--project-description` directly to `sovara record`.
+4. Use `sovara projects` when scope is ambiguous. Commands such as `sovara runs ...`, `sovara annotations ...`, and `sovara priors ...` accept `--project-id` / `--proj-id` with a full ID or unambiguous prefix.
+5. Install or refresh this shared skill only when asked: `sovara install-skill [--level global|project] [--project-dir <dir>] [--target codex|claude|both]`.
+
+## Task Routing
+
+Read only the file that matches the user's task:
+
+- **[optimizing-agents.md](optimizing-agents.md)**: Record, probe, annotate, and improve agent runs; create and manage priors. Use for day-to-day Sovara workflows.
+- **[install-desktop-app.md](install-desktop-app.md)**: Shared OS-level install steps (desktop app, CLI, assistant skill). Load alongside the language-specific install file below.
+- **[install-python-sdk.md](install-python-sdk.md)**: Install the Python SDK (`sovara`) and instrument a Python agent. Pair with `install-desktop-app.md`.
+- **[install-ts-sdk.md](install-ts-sdk.md)**: Install the TypeScript runner (`@sovara/runner`) and instrument a Node.js agent. Pair with `install-desktop-app.md`.
+- **[enterprise-azure.md](enterprise-azure.md)**: Deploy `sovara-server` on Azure Container Apps with Microsoft Entra app registrations.
+- **[enterprise-palantir.md](enterprise-palantir.md)**: Configure Sovara Server to use Palantir Foundry for ontology-backed storage and AIP embeddings.
+
+If the task spans multiple files, read them in this order: install first, optimize second, enterprise/provider setup last. Apply only the sections that match the request.
+
+## On-Demand References
+
+- **[references/cli-reference.md](references/cli-reference.md)**: Load only when exact flags, command shapes, output schemas, or troubleshooting details are needed.
+- **[evals/evals.json](evals/evals.json)**: Output evals — schema-compliant test cases for whether the loaded skill produces good agent behavior.
+- **[evals/trigger_queries.json](evals/trigger_queries.json)**: Trigger evals — realistic prompts (with and without the word "Sovara") used to test whether the description fires correctly. Do not load when answering user requests; this file is for skill maintainers.
+
+## Feedback
+
+When a Sovara command should work but does not, propose posting in the Sovara Discord at [discord.gg/P6a93bWJ](https://discord.gg/P6a93bWJ) or emailing `support@sovara-labs.com`. Include the exact command, sanitized output, OS, Sovara CLI version, and whether the desktop app or enterprise server was running.