sovara 0.2.4__tar.gz → 0.2.6__tar.gz

{sovara-0.2.4 → sovara-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sovara
-Version: 0.2.4
+Version: 0.2.6
 Summary: A development tool for LLM call visualization and debugging
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -8,6 +8,8 @@ License-File: LICENSE
 Requires-Dist: pyyaml
 Requires-Dist: dill
 Requires-Dist: boto3
+Requires-Dist: bm25s
+Requires-Dist: cohere
 Requires-Dist: debugpy
 Requires-Dist: psutil
 Requires-Dist: psycopg2-binary
@@ -20,14 +22,15 @@ Requires-Dist: google-auth
 Requires-Dist: google-cloud-aiplatform
 Requires-Dist: flatten_dict
 Requires-Dist: flatten_json
+Requires-Dist: pymongo
 Provides-Extra: dev
 Requires-Dist: black==25.1.0; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pre-commit; extra == "dev"
 Requires-Dist: responses; extra == "dev"
+Requires-Dist: mongomock; extra == "dev"
 Requires-Dist: openai; extra == "dev"
 Requires-Dist: anthropic; extra == "dev"
-Requires-Dist: openai-agents; extra == "dev"
 Requires-Dist: google-genai; extra == "dev"
 Requires-Dist: hydra-core; extra == "dev"
 Requires-Dist: e2b_code_interpreter; extra == "dev"
@@ -43,6 +46,7 @@ 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"
 Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.5; extra == "docs"
 Requires-Dist: mkdocs-minify-plugin; extra == "docs"

{sovara-0.2.4 → sovara-0.2.6}/pyproject.toml

@@ -26,7 +26,7 @@ line-length = 100
 
 [project]
 name = "sovara"
-version = "0.2.4"
+version = "0.2.6"
 description = "A development tool for LLM call visualization and debugging"
 readme = "docs/release/PYPI_DESC.md"
 requires-python = ">=3.10"
@@ -35,6 +35,8 @@ dependencies = [
     "pyyaml",
     "dill",
     "boto3",
+    "bm25s",
+    "cohere",
     "debugpy",
     "psutil",
     "psycopg2-binary",
@@ -46,7 +48,8 @@ dependencies = [
     "google-auth",
     "google-cloud-aiplatform",
     "flatten_dict",
-    "flatten_json"
+    "flatten_json",
+    "pymongo"
 ]
 
 [project.optional-dependencies]
@@ -55,9 +58,9 @@ dev = [
     "pytest",
     "pre-commit",
     "responses",
+    "mongomock",
     "openai",
     "anthropic",
-    "openai-agents",
     "google-genai",
     "hydra-core",
     "e2b_code_interpreter",
@@ -76,7 +79,8 @@ examples = [
     "openai",
     "anthropic",
     "openai-agents",
-    "google-genai"
+    "google-genai",
+    "claude-agent-sdk"
 ]
 
 docs = [

{sovara-0.2.4 → sovara-0.2.6}/src/sovara/assets/SKILL.md

@@ -19,6 +19,7 @@ description: sovara helps you develop and maintain adaptable agentic systems. It
 2. **Check setup state before the first run**: Start with `uv run so-cli status --path <script-or-project-dir>`. This reports whether the local Sovara user is configured and whether the target directory already belongs to a Sovara project.
 3. **Initialize explicitly when setup is missing**: If the user or project is missing, run `uv run so-cli init --user-name "<full name>" --user-email "<email>" [--project-root <dir> --project-name "<name>"]`. Do not reason about `~/.sovara/.user_id` or `.sovara/.project_id` directly if the CLI can tell you the setup state.
 4. **For non-interactive runs, pass setup through the CLI**: When running through Codex or another non-interactive shell, do not rely on prompts. Use `so-cli init` first or pass `--user-name`, `--user-email`, `--project-root`, `--project-name`, and `--project-description` directly to `so-cli record`.
+5. **Use explicit project selection when needed**: Run `uv run so-cli projects` to list visible projects and their `project_id`s. Project-scoped CLI commands such as `so-cli runs ...` and `so-cli priors ...` accept `--project-id` / `--proj-id`, and these flags accept any unambiguous project-id prefix. If you do not pass a project ID, priors commands resolve scope from the client workspace. Do not assume the server process's cwd will select the right project.
 
 ## Integrated Observability
 
@@ -417,7 +418,9 @@ Then compare results across the three runs using `so-cli probe` and `so-cli runs
 
 ## Priors
 
-Priors are small snippets that augment a context at runtime to inform the agent of specifics like company policies, specific domain knowledge, or conventions. Priors are organized in folders (e.g. `beaver/retriever/`) so different parts of an agent system can have their own priors. `so-cli` provides capability to create and manage priors.
+Priors are small snippets that augment a context at runtime to inform the agent of specifics like company policies, specific domain knowledge, or conventions. Priors are organized in folders (e.g. `path/to/subfolder/`) so different parts of an agent system can have their own priors. `so-cli` provides capability to create and manage priors.
+
+**Default retrieval scope:** Automatic runtime prior injection is the default and is project-wide. It retrieves from root scope (`""`), so it can consider priors anywhere in the project, including subfolders. Use folders for organization, or to narrow scope explicitly with `inject_priors(path="path/to/subfolder/", ...)`. If you manually call `inject_priors(...)`, that inserts a managed `<sovara-priors>` block and automatic retrieval for that same call is skipped.
 
 ### When to use
 If injecting additional information that resolves ambiguity, introduces domain knowledge, or specifies company policy, can resolve the issue – construct a prior.
@@ -429,6 +432,23 @@ The ideal prior has three properties:
 
 Once you have constructed a prior, check if the problem is solved by doing A/B testing. You should inject the prior at any point you see fit, and use the `edit-and-rerun` functionality. If you want to try different versions of the prior, run `edit-and-rerun` in parallel.
 Once you verified that the prior addresses the problem, retrieve the available priors, and check if you introduced a conflict with another prior. If so, resolve the conflict by iteratively tuning and running the agent with the adapted priors, until you are satisfied.
+If the prior came from debugging or improving a specific Sovara run, attach that provenance when you save it: pass `--run-id <full_run_uuid>` to `so-cli priors create` or `so-cli priors update`. Use the full UUID from `so-cli record` or `so-cli runs`; unlike `probe` and `logs`, this field should not use a short prefix.
+When you learned the prior from a concrete run and omit `--run-id`, treat that as a mistake and fix it before you move on. The only normal case for a missing `run_id` is when the prior came from broad repository inspection or synthesis across multiple runs rather than one specific trace.
+
+When a prior constrains correctness, also attach prior-adherence metadata:
+
+- `--consequence-if-not-followed`: the concrete failure mode expected when the prior is relevant but the model violates it.
+- `--non-adherence-severity`: an integer from 1 to 10 used as the fixed penalty when the adherence judge finds the prior relevant and not followed.
+
+Use this severity scale:
+
+- `1-2`: cosmetic or negligible; unlikely to affect outcome
+- `3-4`: minor quality, consistency, or preference issue
+- `5-6`: material correctness or interpretation risk
+- `7-8`: serious issue likely to cause wrong output, wrong action, output-contract violation, or major degradation
+- `9-10`: direct correctness break, safety-critical violation, hard contract violation, or likely primary reason the step failed
+
+The adherence judge decides whether the prior was relevant and followed, but it does not reinterpret the severity. If the prior is violated, the stored `non_adherence_severity` is used as-is.
 
 ### How to use
 
@@ -438,7 +458,7 @@ First, inject priors into the context by modifying the user code.
 from sovara.runner.priors import inject_priors
 
 # Inject all priors from a specific folder into a <sovara-priors> block
-priors_context = inject_priors(path="beaver/retriever/")
+priors_context = inject_priors(path="path/to/subfolder/")
 
 # Prepend to your prompt
 prompt = f"{priors_context}\n\n{user_query}" if priors_context else user_query
@@ -453,7 +473,7 @@ If you want LLM-filtered retrieval instead of loading all priors in a path:
 
 ```python
 priors_context = inject_priors(
-    path="beaver/retriever/",
+    path="path/to/subfolder/",
     context=user_query,
     method="retrieve",
 )
@@ -469,12 +489,29 @@ priors_context = inject_priors(
 usage: so-cli priors [-h] {start-server,list,get,create,update,delete,query,retrieve,migrate,restructure,ls,mkdir,mv,cp,rm} ...
 ```
 
+When you need to target a project explicitly, list projects first:
+
+```bash
+uv run so-cli projects
+```
+
+Then pass `--project-id` or `--proj-id` with a full project ID or any unambiguous prefix:
+
+```bash
+uv run so-cli runs --project-id a6cbns64
+uv run so-cli priors ls --proj-id a6cbns64
+uv run so-cli priors ls path/to/subfolder/ --proj-id a6cbns64
+uv run so-cli priors create --title "<title>" --content "<content>" --summary "<summary>" --path "path/to/subfolder/" --consequence-if-not-followed "<failure mode>" --non-adherence-severity <severity_1_to_10> --project-id a6cbns64
+```
+
+For root scope, omit the path entirely. Examples: `uv run so-cli priors ls --project-id a6cbns64`, `uv run so-cli priors list --project-id a6cbns64`, or `uv run so-cli priors retrieve "<context>" --project-id a6cbns64`.
+
 The main commands are:
 
 - `list`: list priors, optionally filtered by `--path`
 - `get <prior_id>`: fetch one prior
-- `create`: create a prior; supports `--creation-trace-id` and `--trace-source`
-- `update <prior_id>`: update `--name`, `--summary`, `--content`, and/or `--path`
+- `create`: create a prior with `--title`, `--content`, and optional `--summary`, `--path`, `--run-id`, `--when-to-use`, `--consequence-if-not-followed`, `--non-adherence-severity`, `--alias`, `--keyword`, and `--related-prior`. If you omit `--summary`, the server generates one with a cheap model and a fallback. Pass `--run-id <full_run_uuid>` whenever the prior came from a specific run; if you just verified a fix with `so-cli record`, this should usually be present.
+- `update <prior_id>`: update `--title`, `--content`, `--path`, `--run-id`, `--when-to-use`, `--consequence-if-not-followed`, `--non-adherence-severity`, `--alias`, `--keyword`, and/or `--related-prior`. Preserve or add `--run-id <full_run_uuid>` when the prior is tied to a run; do not drop provenance during follow-up edits.
 - `delete <prior_id>`: delete one prior
 - `query`: return all priors in a path plus an injected `<sovara-priors>` block
 - `retrieve "<context>"`: use the LLM retriever to select relevant priors
@@ -485,21 +522,21 @@ The main commands are:
 Examples:
 
 ```bash
-so-cli priors list --path "beaver/retriever/"
+so-cli priors list --path "path/to/subfolder/"
 so-cli priors get <prior_id>
-so-cli priors create --name "<name>" --summary "<summary>" --content "<content>" --path "beaver/retriever/"
-so-cli priors update <prior_id> --content "<new_content>" --path "beaver/validator/"
+so-cli priors create --title "<title>" --content "<content>" --summary "<summary>" --path "path/to/subfolder/" --run-id "<full_run_uuid>" --consequence-if-not-followed "<failure mode>" --non-adherence-severity <severity_1_to_10> --alias "<alias>" --keyword "<keyword>" --related-prior "<prior_id>"
+so-cli priors update <prior_id> --content "<new_content>" --path "path/to/another-subfolder/" --consequence-if-not-followed "<failure mode>" --non-adherence-severity <severity_1_to_10> --alias "<alias>" --keyword "<keyword>"
 so-cli priors delete <prior_id>
-so-cli priors query --path "beaver/retriever/"
-so-cli priors retrieve "Find SQL validation guidance" --path "beaver/"
+so-cli priors query --path "path/to/subfolder/"
+so-cli priors retrieve "Find validation guidance"
 so-cli priors migrate
-so-cli priors restructure propose --path "beaver/" --comments "Group priors by subsystem" > proposal.json
+so-cli priors restructure propose --path "path/to/root/" --comments "Group priors by subsystem" > proposal.json
 so-cli priors restructure execute --proposal-file proposal.json
 so-cli priors restructure abort <task_id>
-so-cli priors ls beaver/
-so-cli priors mv -i abc123,def456 beaver/dest/
-so-cli priors cp beaver/retriever/ beaver/retriever-backup/
-so-cli priors rm -r beaver/old/
+so-cli priors ls
+so-cli priors mv -i abc123,def456 path/to/destination/
+so-cli priors cp path/to/subfolder/ path/to/subfolder-backup/
+so-cli priors rm -r path/to/old-folder/
 ```
 
 Restructure workflow:
@@ -511,30 +548,58 @@ Restructure workflow:
 
 Representative outputs:
 
-`so-cli priors list` returns a JSON array:
+`so-cli priors list` returns a JSON object:
 
 ```json
-[
-  {
-    "id": "24d90294",
-    "name": "Rate Limiting Best Practices",
-    "summary": "How to implement exponential backoff for API rate limits",
-    "content": "When dealing with rate limits, implement exponential backoff...",
-    "path": "beaver/retriever/"
-  }
-]
+{
+  "priors": [
+    {
+      "id": "24d90294",
+      "title": "Rate Limiting Best Practices",
+      "summary": "Use exponential backoff with jitter when upstream APIs rate-limit requests.",
+      "content": "When dealing with rate limits, implement exponential backoff...",
+      "path": "path/to/subfolder/",
+      "prior_status": "active",
+      "run_id": "<run_uuid_or_null>",
+      "consequence_if_not_followed": "Violating this prior can cause retries to duplicate side-effecting calls.",
+      "non_adherence_severity": "<integer_1_to_10>",
+      "aliases": ["rate limit retries", "429 retry policy"],
+      "keywords": ["rate-limit", "backoff", "jitter", "429"],
+      "related_priors": []
+    }
+  ]
+}
 ```
 
+Active priors now store:
+
+- `title`: mandatory, separate from the markdown body
+- `summary`: mandatory persisted summary; generated by the cheap model with a fallback unless you pass `--summary` on create
+- `content`: mandatory raw markdown without a title heading
+- `status`: active or draft
+- `run_id`: optional source trace/run UUID; pass it whenever the prior was derived from a specific run
+- `consequence_if_not_followed`: optional expected failure mode when a relevant prior is violated
+- `non_adherence_severity`: optional integer `1-10` fixed severity penalty for a violated relevant prior
+- `aliases`, `keywords`, `related_priors`: optional string lists
+- `created_at`, `updated_at`: UTC timestamps
+- `validation_metadata`: latest validation payload
+
 `so-cli priors create` returns the server's creation response:
 
 ```json
 {
   "status": "created",
   "id": "<prior_id>",
-  "name": "<name>",
-  "summary": "<summary>",
+  "title": "<title>",
+  "summary": "<manual_or_generated_summary>",
   "content": "<content>",
-  "path": "beaver/retriever/"
+  "path": "path/to/subfolder/",
+  "run_id": "<run_uuid_or_null>",
+  "consequence_if_not_followed": "<failure_mode_or_empty_string>",
+  "non_adherence_severity": "<integer_1_to_10>",
+  "aliases": ["<manual_or_generated_alias>"],
+  "keywords": ["<manual_or_generated_keyword>"],
+  "related_priors": ["<prior_id>"]
 }
 ```
 
@@ -542,14 +607,14 @@ Representative outputs:
 
 ```json
 {
-  "path": "beaver/retriever/",
+  "path": "path/to/subfolder/",
   "priors": [
     {
       "id": "<prior_id>",
       "name": "<name>",
       "summary": "<summary>",
       "content": "<content>",
-      "path": "beaver/retriever/"
+      "path": "path/to/subfolder/"
     }
   ],
   "injected_context": "<sovara-priors>\n<!-- {\"priors\":[{\"id\":\"<prior_id>\"}]} -->\n## <name>\n<content>\n</sovara-priors>"
@@ -561,14 +626,14 @@ Representative outputs:
 ```json
 {
   "context": "Find SQL validation guidance",
-  "base_path": "beaver/",
+  "base_path": "path/to/root/",
   "priors": [
     {
       "id": "<prior_id>",
       "name": "<name>",
       "summary": "<summary>",
       "content": "<content>",
-      "path": "beaver/validator/"
+      "path": "path/to/another-subfolder/"
     }
   ],
   "prior_count": 1
@@ -581,13 +646,13 @@ Representative outputs:
 {
   "task_id": "<task_id>",
   "summary": "<summary>",
-  "new_folders": ["beaver/validator/"],
+  "new_folders": ["path/to/another-subfolder/"],
   "removed_folders": [],
   "moves": [
     {
       "prior_id": "<prior_id>",
-      "current_path": "beaver/",
-      "new_path": "beaver/validator/",
+      "current_path": "path/to/root/",
+      "new_path": "path/to/another-subfolder/",
       "reason": "<reason>"
     }
   ],
@@ -601,10 +666,10 @@ Representative outputs:
 
 ```json
 {
-  "path": "beaver/",
+  "path": "path/to/root/",
   "folders": [
     {
-      "path": "beaver/retriever/",
+      "path": "path/to/subfolder/",
       "prior_count": 3
     }
   ],
@@ -614,7 +679,7 @@ Representative outputs:
       "name": "Some Prior",
       "summary": "...",
       "content": "...",
-      "path": "beaver/"
+      "path": "path/to/root/"
     }
   ],
   "prior_count": 4
@@ -626,7 +691,7 @@ Representative outputs:
 ```json
 {
   "status": "moved",
-  "dst": "beaver/dest/",
+  "dst": "path/to/destination/",
   "moved_count": 2
 }
 ```

sovara-0.2.6/src/sovara/assets/web_app/assets/AttachmentPreview-Di2_OG_9.js

@@ -0,0 +1 @@
+import{r,j as e}from"./index-Cu0VGrcx.js";import{D as n,a as l,P as o,G as p}from"./DocumentPreviewModal-CvQFa4di.js";import{M as c,i as d,a as h,h as u,s as x,d as j}from"./RunRoute-BXKXUvYa.js";import"./tiny-invariant-BCXflckp.js";import"./LayoutBreadcrumb-CJhx8VyY.js";import"./tierState-CVxZC5KD.js";import"./navigation-BBqqpNGD.js";import"./runtime-rMDdBrlz.js";import"./plus-LepfYku6.js";import"./value-BlxarHmt.js";import"./prismTheme-BK3YfG66.js";import"./useTheme-BfCfHZeA.js";p.workerSrc=new URL("/assets/pdf.worker.min-qwK7q_zL.mjs",import.meta.url).toString();function b({attachment:m,onClick:i}){const s=`data:${m.mimeType};base64,${m.data}`,t=c[m.mimeType]??m.mimeType.split("/")[1]?.toUpperCase()??"FILE";return e.jsxs("button",{className:"attachment-thumb",onClick:i,title:m.name,children:[e.jsx("div",{className:"attachment-thumb-preview",children:d(m.mimeType)?e.jsx("img",{src:s,alt:m.name,className:"attachment-thumb-img"}):h(m.mimeType)?e.jsx(l,{file:s,loading:e.jsx("div",{className:"attachment-thumb-placeholder",children:"PDF"}),children:e.jsx(o,{pageNumber:1,width:120,renderTextLayer:!1,renderAnnotationLayer:!1})}):e.jsx("div",{className:"attachment-thumb-placeholder",children:t})}),e.jsxs("div",{className:"attachment-thumb-label",children:[e.jsx("span",{className:"attachment-thumb-ext",children:t}),e.jsx("span",{className:"attachment-thumb-name",children:m.name})]})]})}function E({attachments:m}){const[i,s]=r.useState(null);if(m.length===0)return null;function t(a){u(a.mimeType)?s(a):x(j(a.data,{mime_type:a.mimeType,filename:a.name})||{data:a.data,mimeType:a.mimeType,type:"unknown",name:a.name})}return e.jsxs(e.Fragment,{children:[e.jsx("div",{className:"attachment-strip",children:m.map(a=>e.jsx(b,{attachment:a,onClick:()=>t(a)},a.id))}),i&&e.jsx(n,{attachment:i,onClose:()=>s(null)})]})}export{E as AttachmentStrip};