sovara 0.2.1__tar.gz → 0.2.3__tar.gz

{sovara-0.2.1 → sovara-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sovara
-Version: 0.2.1
+Version: 0.2.3
 Summary: A development tool for LLM call visualization and debugging
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -33,6 +33,8 @@ Requires-Dist: langchain; extra == "dev"
 Requires-Dist: langchain-anthropic; extra == "dev"
 Requires-Dist: langchain-openai; extra == "dev"
 Requires-Dist: websocket-client; extra == "dev"
+Provides-Extra: desktop
+Requires-Dist: pyinstaller>=6.11; extra == "desktop"
 Provides-Extra: examples
 Requires-Dist: openai; extra == "examples"
 Requires-Dist: anthropic; extra == "examples"

{sovara-0.2.1 → sovara-0.2.3}/pyproject.toml

@@ -5,7 +5,7 @@ requires = ["setuptools"]
 build-backend = "setuptools.build_meta"
 
 [tool.setuptools.package-data]
-"sovara.assets" = ["SKILL.md"]
+"sovara.assets" = ["SKILL.md", "web_app/**/*"]
 
 [tool.setuptools]
 package-dir = {"" = "src"}
@@ -26,7 +26,7 @@ line-length = 100
 
 [project]
 name = "sovara"
-version = "0.2.1"
+version = "0.2.3"
 description = "A development tool for LLM call visualization and debugging"
 readme = "docs/release/PYPI_DESC.md"
 requires-python = ">=3.10"
@@ -65,6 +65,10 @@ dev = [
     "websocket-client"
 ]
 
+desktop = [
+    "pyinstaller>=6.11",
+]
+
 examples = [
     "openai",
     "anthropic",

{sovara-0.2.1 → sovara-0.2.3}/src/sovara/assets/SKILL.md

@@ -208,6 +208,40 @@ This will produce the full result (no preview) of the specific keys that match t
 }
 ```
 
+### Inspect persisted logs
+If you want to inspect the captured stdout/stderr transcript for a run, use the `logs` command. Unlike `probe` and `runs`, this command prints plain text rather than JSON.
+
+The tool is generally structured like this.
+
+```
+usage: so-cli logs [-h] [--tail TAIL] [--grep GREP] [--context CONTEXT] [--line-numbers] run_id
+
+positional arguments:
+  run_id                Run ID to fetch logs for
+
+options:
+  -h, --help            show this help message and exit
+  --tail TAIL           Show only the last N displayed lines
+  --grep GREP           Filter displayed lines using a regex pattern
+  --context CONTEXT     Show N lines of context around each grep match
+  --line-numbers        Prefix displayed lines with original line numbers
+```
+
+`run_id` accepts a full UUID or any unambiguous prefix, just like `probe`.
+
+Examples:
+To inspect the last 40 lines of a run, run
+
+```bash
+uv run so-cli logs b6aaf796 --tail 40
+```
+
+To search a large log for cache misses with nearby context and original line numbers, run
+
+```bash
+uv run so-cli logs b6aaf796 --grep "Cache miss" --context 2 --line-numbers
+```
+
 ### List and manage runs
 You can manage past runs that you did with the `runs` command, which is structured in the following way
 

{sovara-0.2.1 → sovara-0.2.3}/src/sovara/cli/so_record.py

@@ -3,7 +3,6 @@ import time
 import yaml
 from argparse import ArgumentParser, REMAINDER
 from sovara.common.constants import SOVARA_CONFIG
-from sovara.runner.agent_runner import AgentRunner
 
 
 def launch_command_parser():
@@ -32,6 +31,13 @@ def launch_command_parser():
         help="Change each process to interpret the launch script as a Python module, executing with the same behavior as 'python -m'.",
     )
 
+    parser.add_argument(
+        "-u",
+        "--unbuffered",
+        action="store_true",
+        help="Run with unbuffered stdout/stderr, like 'python -u'.",
+    )
+
     parser.add_argument(
         "script_path",
         type=str,
@@ -71,12 +77,15 @@ def _validate_launch_command(args):
 
 
 def launch_command(args):
+    from sovara.runner.agent_runner import AgentRunner
+
     args = _validate_launch_command(args)
 
     agent_runner = AgentRunner(
         script_path=args.script_path,
         script_args=args.script_args,
         is_module_execution=args.module,
+        unbuffered=args.unbuffered,
         run_name=args.run_name,
     )
     agent_runner.run()

{sovara-0.2.1 → sovara-0.2.3}/src/sovara/cli/so_server.py

@@ -12,9 +12,10 @@ if package_parent not in sys.path:
 import time
 import subprocess
 import json
-from argparse import ArgumentParser
+from argparse import ArgumentParser, SUPPRESS
 
 from sovara.common.logger import logger, create_file_logger
+from sovara.common.runtime import build_so_server_command
 
 from sovara.common.constants import (
     MAIN_SERVER_LOG,
@@ -22,6 +23,7 @@ from sovara.common.constants import (
     INFERENCE_SERVER_LOG,
     MAIN_SERVER_STARTUP_LOCK,
     HOST,
+    INFERENCE_PORT,
     PORT,
     SHUTDOWN_WAIT,
 )
@@ -127,7 +129,7 @@ def launch_daemon_server() -> bool:
     try:
         with open(MAIN_SERVER_LOG, "a+") as log_f:
             subprocess.Popen(
-                [sys.executable, "-m", "sovara.cli.so_server", "_serve"],
+                build_so_server_command("_serve", "--host", HOST, "--port", str(PORT)),
                 close_fds=True,
                 start_new_session=True,
                 stdin=subprocess.DEVNULL,
@@ -160,12 +162,61 @@ def server_command_parser():
             "clear-logs",
             "_clear_cache",
             "_serve",
+            "_serve-inference",
         ],
         help="The command to execute for the server.",
     )
+    parser.add_argument("--host", default=None, help=SUPPRESS)
+    parser.add_argument("--port", type=int, default=None, help=SUPPRESS)
     return parser
 
 
+def _serve_main_server(host: str, port: int) -> None:
+    _server_logger.info(f"Imports completed in {_time.time() - _import_start:.2f}s")
+
+    # Save Python executable path to config for VS Code extension to use
+    from sovara.common.constants import SOVARA_CONFIG
+    from sovara.common.config import Config
+
+    try:
+        config = Config.from_yaml_file(SOVARA_CONFIG)
+        if config.python_executable != sys.executable:
+            config.python_executable = sys.executable
+            config.to_yaml_file(SOVARA_CONFIG)
+            _server_logger.info(f"Saved python_executable: {sys.executable}")
+    except Exception as e:
+        _server_logger.warning(f"Could not save python_executable: {e}")
+
+    import uvicorn
+    from sovara.server.app import create_app
+
+    _start = _time.time()
+    app = create_app()
+    _server_logger.info(f"FastAPI app created in {_time.time() - _start:.2f}s")
+
+    # Use Config+Server instead of uvicorn.run() so we can set
+    # server.should_exit = True for clean programmatic shutdown.
+    uv_config = uvicorn.Config(app, host=host, port=port, log_level="warning")
+    uv_server = uvicorn.Server(uv_config)
+
+    # Store reference on app so lifespan can wire it into ServerState.
+    app.state.uvicorn_server = uv_server
+    try:
+        uv_server.run()
+    finally:
+        try:
+            _stop_child_servers()
+        except Exception as exc:
+            _server_logger.warning(f"Could not stop child servers during shutdown: {exc}")
+        _release_startup_lock()
+
+
+def _serve_inference_server(host: str, port: int) -> None:
+    from sovara.server.graph_analysis.inference_server import serve
+
+    serve(host=host, port=port)
+
+
 def execute_server_command(args):
     if args.command == "start":
         if _is_server_running():
@@ -250,43 +301,12 @@ def execute_server_command(args):
         return
 
     elif args.command == "_serve":
-        _server_logger.info(f"Imports completed in {_time.time() - _import_start:.2f}s")
-
-        # Save Python executable path to config for VS Code extension to use
-        from sovara.common.constants import SOVARA_CONFIG
-        from sovara.common.config import Config
-
-        try:
-            config = Config.from_yaml_file(SOVARA_CONFIG)
-            if config.python_executable != sys.executable:
-                config.python_executable = sys.executable
-                config.to_yaml_file(SOVARA_CONFIG)
-                _server_logger.info(f"Saved python_executable: {sys.executable}")
-        except Exception as e:
-            _server_logger.warning(f"Could not save python_executable: {e}")
-
-        import uvicorn
-        from sovara.server.app import create_app
-
-        _start = _time.time()
-        app = create_app()
-        _server_logger.info(f"FastAPI app created in {_time.time() - _start:.2f}s")
-
-        # Use Config+Server instead of uvicorn.run() so we can set
-        # server.should_exit = True for clean programmatic shutdown.
-        uv_config = uvicorn.Config(app, host=HOST, port=PORT, log_level="warning")
-        uv_server = uvicorn.Server(uv_config)
+        _serve_main_server(args.host or HOST, args.port or PORT)
+        return
 
-        # Store reference on app so lifespan can wire it into ServerState.
-        app.state.uvicorn_server = uv_server
-        try:
-            uv_server.run()
-        finally:
-            try:
-                _stop_child_servers()
-            except Exception as exc:
-                _server_logger.warning(f"Could not stop child servers during shutdown: {exc}")
-            _release_startup_lock()
+    elif args.command == "_serve-inference":
+        _serve_inference_server(args.host or HOST, args.port or INFERENCE_PORT)
+        return
 
 
 def main():

{sovara-0.2.1 → sovara-0.2.3}/src/sovara/cli/so_tool.py

@@ -2,6 +2,7 @@ import atexit
 import os
 import sys
 import json
+import re
 import shlex
 import shutil
 import uuid
@@ -190,6 +191,77 @@ def _fetch_all_runs() -> list[dict]:
     return runs
 
 
+def format_log_output(
+    log_text: str,
+    *,
+    tail: int | None = None,
+    grep: str | None = None,
+    context: int = 0,
+    line_numbers: bool = False,
+) -> str:
+    """Render persisted run logs with optional filtering and line-number formatting."""
+    if tail is not None and tail < 0:
+        raise ValueError("--tail must be greater than or equal to 0")
+    if context < 0:
+        raise ValueError("--context must be greater than or equal to 0")
+
+    if grep is None and tail is None and context == 0 and not line_numbers:
+        return log_text
+
+    lines = log_text.splitlines()
+    entries: list[tuple[int, str] | None]
+
+    if grep:
+        try:
+            pattern = re.compile(grep)
+        except re.error as exc:
+            raise ValueError(f"Invalid regex: {exc}") from exc
+
+        ranges: list[tuple[int, int]] = []
+        for index, line in enumerate(lines):
+            if not pattern.search(line):
+                continue
+
+            start = max(0, index - context)
+            end = min(len(lines) - 1, index + context)
+            if ranges and start <= ranges[-1][1] + 1:
+                ranges[-1] = (ranges[-1][0], max(ranges[-1][1], end))
+            else:
+                ranges.append((start, end))
+
+        entries = []
+        for range_index, (start, end) in enumerate(ranges):
+            if range_index > 0:
+                entries.append(None)
+            for line_index in range(start, end + 1):
+                entries.append((line_index + 1, lines[line_index]))
+    else:
+        entries = [(index + 1, line) for index, line in enumerate(lines)]
+
+    if tail is not None:
+        entries = entries[-tail:] if tail > 0 else []
+
+    if not entries:
+        return ""
+
+    numbered_lines = [entry for entry in entries if entry is not None]
+    number_width = len(str(max((line_number for line_number, _line in numbered_lines), default=1)))
+
+    rendered_lines: list[str] = []
+    for entry in entries:
+        if entry is None:
+            rendered_lines.append("--")
+            continue
+
+        line_number, line = entry
+        if line_numbers:
+            rendered_lines.append(f"{line_number:>{number_width}}: {line}")
+        else:
+            rendered_lines.append(line)
+
+    return "\n".join(rendered_lines) + "\n"
+
+
 def _spawn_rerun(prepared: dict, timeout: float | None = None) -> dict:
     """
     Spawn a rerun process for a run and block until completion.
@@ -311,11 +383,16 @@ def record_command(args) -> None:
 
     atexit.register(cleanup_run_file)
 
-    cmd = [sys.executable, "-m", "sovara.cli.so_record"]
+    cmd = [sys.executable]
+    if args.unbuffered:
+        cmd.append("-u")
+    cmd.extend(["-m", "sovara.cli.so_record"])
     if args.run_name:
         cmd.extend(["--run-name", args.run_name])
     if args.module:
         cmd.append("-m")
+    if args.unbuffered:
+        cmd.append("-u")
     cmd.append(args.script_path)
     cmd.extend(args.script_args)
 
@@ -382,6 +459,27 @@ def probe_command(args) -> None:
     output_json(result)
 
 
+def logs_command(args) -> None:
+    """Show the persisted log for a run."""
+    result = _server_request("GET", f"/ui/run/{args.run_id}/log")
+    if result.get("status") == "error":
+        output_json(result)
+
+    try:
+        rendered = format_log_output(
+            result.get("log", ""),
+            tail=args.tail,
+            grep=args.grep,
+            context=args.context,
+            line_numbers=args.line_numbers,
+        )
+    except ValueError as exc:
+        output_json({"status": "error", "error": str(exc)})
+
+    sys.stdout.write(rendered)
+    sys.stdout.flush()
+
+
 def runs_command(args) -> None:
     """List runs via the REST API."""
     import re
@@ -965,7 +1063,7 @@ def create_parser() -> ArgumentParser:
     """Create the argument parser with subcommands."""
     parser = ArgumentParser(
         prog="so-cli",
-        description="CLI for programmatic interaction with Sovara dataflow system. All output is JSON.",
+        description="CLI for programmatic interaction with Sovara dataflow system. Most commands output JSON; `logs` outputs plain text.",
     )
     subparsers = parser.add_subparsers(dest="command", required=True)
 
@@ -980,6 +1078,11 @@ def create_parser() -> ArgumentParser:
         action="store_true",
         help="Run script_path as a Python module (like python -m)",
     )
+    record.add_argument(
+        "-u", "--unbuffered",
+        action="store_true",
+        help="Run with unbuffered stdout/stderr, like python -u",
+    )
     record.add_argument("--run-name", help="Human-readable name for this run")
     record.add_argument(
         "--timeout",
@@ -1028,6 +1131,33 @@ def create_parser() -> ArgumentParser:
         help="Filter keys using regex pattern on flattened keys (e.g., 'messages.*content'). Lists use index notation: content.0.hello",
     )
 
+    logs = subparsers.add_parser(
+        "logs",
+        help="Show a run's persisted logs",
+        description="Show the persisted log transcript for a run with optional filtering.",
+    )
+    logs.add_argument("run_id", help="Run UUID or unambiguous prefix to fetch logs for")
+    logs.add_argument(
+        "--tail",
+        type=int,
+        help="Show only the last N displayed lines",
+    )
+    logs.add_argument(
+        "--grep",
+        help="Filter displayed lines using a regex pattern",
+    )
+    logs.add_argument(
+        "--context",
+        type=int,
+        default=0,
+        help="Show N lines of context around each grep match",
+    )
+    logs.add_argument(
+        "--line-numbers",
+        action="store_true",
+        help="Prefix displayed lines with original line numbers",
+    )
+
     # runs subcommand
     runs = subparsers.add_parser(
         "runs",
@@ -1356,6 +1486,8 @@ def main():
         record_command(args)
     elif args.command == "probe":
         probe_command(args)
+    elif args.command == "logs":
+        logs_command(args)
     elif args.command == "runs":
         runs_command(args)
     elif args.command == "edit-and-rerun":

sovara-0.2.3/src/sovara/common/runtime.py

@@ -0,0 +1,15 @@
+"""Helpers for launching Sovara subprocesses across source and frozen builds."""
+
+from __future__ import annotations
+
+import sys
+
+
+def is_frozen_runtime() -> bool:
+    return bool(getattr(sys, "frozen", False))
+
+
+def build_so_server_command(*args: str) -> list[str]:
+    if is_frozen_runtime():
+        return [sys.executable, *args]
+    return [sys.executable, "-m", "sovara.cli.so_server", *args]

{sovara-0.2.1 → sovara-0.2.3}/src/sovara/runner/agent_runner.py

@@ -31,6 +31,7 @@ from sovara.runner.context_manager import (
 )
 from sovara.common.utils import set_server_url, http_post
 from sovara.runner.monkey_patching.apply_monkey_patches import apply_all_monkey_patches
+from sovara.runner.run_log_capture import RunLogCapture
 
 
 def _log_error(context: str, exception: Exception) -> None:
@@ -128,12 +129,14 @@ class AgentRunner:
         script_path: str,
         script_args: List[str],
         is_module_execution: bool,
+        unbuffered: bool = False,
         sample_id: Optional[str] = None,
         run_name: Optional[str] = None,
     ):
         self.script_path = script_path
         self.script_args = script_args
         self.is_module_execution = is_module_execution
+        self.unbuffered = unbuffered
         self.sample_id = sample_id
         self.run_name = run_name
 
@@ -238,6 +241,7 @@ class AgentRunner:
         """Generate the appropriate command for restarting the script."""
         original_command = " ".join(shlex.quote(arg) for arg in sys.argv)
         python_executable = sys.executable
+        interpreter_flags = "-u " if self.unbuffered else ""
 
         if not self._is_debugpy_session():
             return f"{python_executable} {original_command}"
@@ -251,20 +255,36 @@ class AgentRunner:
         if "launcher" in cmdline_str and "--" in parent_cmdline:
             dash_index = parent_cmdline.index("--")
             original_args = " ".join(shlex.quote(arg) for arg in parent_cmdline[dash_index + 1:])
-            return f"/usr/bin/env {python_executable} {original_args}"
+            return f"/usr/bin/env {python_executable} {interpreter_flags}{original_args}".strip()
 
         if "-m" in parent_cmdline and "debugpy" in parent_cmdline:
             if self.is_module_execution:
                 target_args = f"-m {self.script_path} {' '.join(shlex.quote(arg) for arg in self.script_args)}"
             else:
                 target_args = f"{shlex.quote(self.script_path)} {' '.join(shlex.quote(arg) for arg in self.script_args)}"
-            return f"{python_executable} {target_args}"
+            return f"{python_executable} {interpreter_flags}{target_args}".strip()
 
         if self.is_module_execution:
             target_args = f"-m {self.script_path} {' '.join(shlex.quote(arg) for arg in self.script_args)}"
         else:
             target_args = f"{shlex.quote(self.script_path)} {' '.join(shlex.quote(arg) for arg in self.script_args)}"
-        return f"{python_executable} {target_args}"
+        return f"{python_executable} {interpreter_flags}{target_args}".strip()
+
+    def _apply_python_runtime_flags(self) -> None:
+        """Apply interpreter-like runtime flags that matter for in-process execution."""
+        if not self.unbuffered:
+            return
+
+        os.environ["PYTHONUNBUFFERED"] = "1"
+        for stream_name in ("stdout", "stderr"):
+            stream = getattr(sys, stream_name, None)
+            reconfigure = getattr(stream, "reconfigure", None)
+            if not callable(reconfigure):
+                continue
+            try:
+                reconfigure(line_buffering=True, write_through=True)
+            except ValueError:
+                logger.debug(f"Could not reconfigure sys.{stream_name} for unbuffered mode")
 
     def _register_with_server(self) -> None:
         """Register with the server via HTTP POST."""
@@ -357,6 +377,23 @@ class AgentRunner:
             traceback.print_exc()
             return 1
 
+    def _append_run_log(self, log_chunk: str) -> None:
+        if not self.run_id or not log_chunk:
+            return
+        http_post("/runner/update-log", {
+            "run_id": self.run_id,
+            "log_text": log_chunk,
+            "replace": False,
+        }, timeout=2.0)
+
+    def _run_user_code_with_output_capture(self) -> int:
+        if not self.run_id:
+            return self._execute_user_code()
+        with RunLogCapture(
+            append_callback=self._append_run_log,
+        ):
+            return self._execute_user_code()
+
     def _run_debug_mode(self) -> int:
         """Run in debug mode with persistent restart loop."""
         logger.info("[AgentRunner] Debug mode detected. Running with restart capability.")
@@ -368,7 +405,7 @@ class AgentRunner:
                 self._apply_runtime_setup()
                 first_run = False
 
-            exit_code = self._execute_user_code()
+            exit_code = self._run_user_code_with_output_capture()
             logger.info(f"[AgentRunner] Script completed with exit code {exit_code}. Waiting...")
 
             while not self.shutdown_flag and not self.restart_event.is_set():
@@ -387,11 +424,12 @@ class AgentRunner:
     def _run_normal_mode(self) -> int:
         """Run in normal mode (single execution)."""
         self._apply_runtime_setup()
-        return self._execute_user_code()
+        return self._run_user_code_with_output_capture()
 
     def run(self) -> None:
         """Main entry point."""
         try:
+            self._apply_python_runtime_flags()
             self._setup_environment()
             ensure_server_running()