severn-trace 0.1.0__py3-none-any.whl

severn/__init__.py

@@ -0,0 +1,17 @@
+"""severn-trace: lightweight execution tracing for autonomous AI agents."""
+
+__version__ = "0.1.0"
+
+from .exporter import Exporter, configure, flush, get_exporter
+from .tracer import FAILED, SUCCESS, trace
+
+__all__ = [
+    "trace",
+    "configure",
+    "flush",
+    "get_exporter",
+    "Exporter",
+    "SUCCESS",
+    "FAILED",
+    "__version__",
+]

severn/cli.py

@@ -0,0 +1,243 @@
+import sys
+import json
+import os
+import time
+
+# Rich Cyberpunk & Terminal ANSI Color Palette
+CYAN = "\033[96m"
+GREEN = "\033[92m"
+YELLOW = "\033[93m"
+MAGENTA = "\033[95m"
+BLUE = "\033[94m"
+RED = "\033[91m"
+WHITE = "\033[97m"
+RESET = "\033[0m"
+BOLD = "\033[1m"
+DIM = "\033[2m"
+ORANGE = "\033[38;5;208m"
+PURPLE = "\033[38;5;141m"
+TEAL = "\033[38;5;38m"
+
+def show_banner():
+    os.system('clear' if os.name == 'posix' else 'cls')
+    
+    # Clean 3D Block ASCII Banner for SEVERN
+    banner = f"""{CYAN}{BOLD}
+ ███████╗███████╗██╗   ██╗███████╗██████╗ ███╗   ██╗
+ ██╔════╝██╔════╝██║   ██║██╔════╝██╔══██╗████╗  ██║
+ ███████╗█████╗  ██║   ██║█████╗  ██████╔╝██╔██╗ ██║
+ ╚════██║██╔══╝  ╚██  ██╔╝██╔══╝  ██╔══██╗██║╚██╗██║
+ ███████║███████╗ ╚████╔╝ ███████╗██║  ██║██║ ╚████║
+ ╚══════╝╚══════╝  ╚═══╝  ╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝
+{RESET}{PURPLE}=================================================================================={RESET}
+{MAGENTA}{BOLD} ⚡ ZERO-DEPENDENCY EXECUTION RUNTIME & ERROR TELEMETRY LAYER FOR AI AGENTS ⚡{RESET}
+{PURPLE}=================================================================================={RESET}
+    """
+    print(banner)
+
+def get_trace_stats():
+    """Analyzes local log files to compute real-time metrics."""
+    log_path = "severn_traces.jsonl"
+    if not os.path.exists(log_path):
+        return 0, 0, 0
+    
+    total = 0
+    passed = 0
+    failed = 0
+    
+    try:
+        with open(log_path, "r", encoding="utf-8") as f:
+            for line in f:
+                total += 1
+                if '"status": "SUCCESS"' in line or '"status":"SUCCESS"' in line:
+                    passed += 1
+                elif '"status": "FAILED"' in line or '"status":"FAILED"' in line:
+                    failed += 1
+    except Exception:
+        pass
+                
+    return total, passed, failed
+
+def pause_and_return():
+    input(f"\n{DIM}Press Enter to return...{RESET}")
+
+# -------------------------------------------------------------------------
+# MULTI-STEP AGENT FRAMEWORK ARCHITECTURE EXPLORER (LangChain / CrewAI / AutoGen)
+# -------------------------------------------------------------------------
+def sub_menu_agent_topology():
+    while True:
+        show_banner()
+        print(f"{TEAL}{BOLD}🤖 AI AGENT FRAMEWORK INTEGRATION & TOPOLOGY RUNTIME:{RESET}\n")
+        print(f"  {GREEN}[1]{RESET} {BOLD}CrewAI Agent Goal & Task Trapping{RESET}")
+        print(f"  {CYAN}[2]{RESET} {BOLD}LangChain AgentExecutor State Machine Tracing{RESET}")
+        print(f"  {YELLOW}[3]{RESET} {BOLD}AutoGen Multi-Agent Conversational Routing{RESET}")
+        print(f"  {MAGENTA}[4]{RESET} {BOLD}Custom Autonomous Loop Pattern (ReAct / Plan-and-Solve){RESET}")
+        print(f"  {RED}[B]{RESET} {BOLD}Back to Main Menu{RESET}\n")
+        
+        choice = input(f"{CYAN}{BOLD}Select framework workflow (1-4 or B): {RESET}").strip().upper()
+        
+        if choice == "1":
+            print(f"\n{GREEN}[+] CrewAI Task Execution Telemetry:{RESET}")
+            print(f"    Wrap sequential/hierarchical CrewAI tasks directly with {BOLD}@trace{RESET}.")
+            print("    Tracks crew role assignments, action output schemas, and tool-retry loops.")
+            pause_and_return()
+        elif choice == "2":
+            print(f"\n{CYAN}[+] LangChain AgentExecutor Hooking:{RESET}")
+            print(f"    Decorate intermediate tool executions and custom LLMChain steps with {BOLD}@trace{RESET}.")
+            print("    Traps tool input parsing errors before state degradation occurs.")
+            pause_and_return()
+        elif choice == "3":
+            print(f"\n{YELLOW}[+] AutoGen Multi-Agent Conversation Tracing:{RESET}")
+            print(f"    Monitor inter-agent messages between ConversableAgent instances.")
+            print("    Logs step duration, message payload sizes, and dead-end conversation loops.")
+            pause_and_return()
+        elif choice == "4":
+            print(f"\n{MAGENTA}[+] Custom ReAct Execution Loop:{RESET}")
+            print(f"    Pattern: {BOLD}Thought -> Action -> Observation -> Final Answer{RESET}")
+            print("    Severn exports structured JSON metadata per step for instant replay analysis.")
+            pause_and_return()
+        elif choice == "B":
+            break
+
+# -------------------------------------------------------------------------
+# LABLAB.AI HACKATHON MULTI-STEP PORTAL
+# -------------------------------------------------------------------------
+def sub_menu_hackathon():
+    while True:
+        show_banner()
+        print(f"{YELLOW}{BOLD}🏆 LABLAB.AI HACKATHON BUILDER PORTAL (MULTI-STEP EXPLORER):{RESET}\n")
+        print(f"  {GREEN}[1]{RESET} {BOLD}Challenge Focus & Multi-Agent Tracks{RESET}")
+        print(f"  {CYAN}[2]{RESET} {BOLD}Participant Tooling & Sponsor Grants{RESET}")
+        print(f"  {MAGENTA}[3]{RESET} {BOLD}Telemetry Submission Guidelines{RESET}")
+        print(f"  {RED}[B]{RESET} {BOLD}Back to Main Menu{RESET}\n")
+        
+        choice = input(f"{CYAN}{BOLD}Select hackathon section (1-3 or B): {RESET}").strip().upper()
+        
+        if choice == "1":
+            print(f"\n{GREEN}[+] Challenge Focus:{RESET}")
+            print("    Architect multi-step AI agents, trap tool-call failure loops,")
+            print("    and provide zero-friction local telemetry using Severn-Trace.")
+            pause_and_return()
+        elif choice == "2":
+            print(f"\n{CYAN}[+] Participant Perks:{RESET}")
+            print("    Access sponsor API credits, developer tooling grants, priority community channels,")
+            print("    and fast-track investor introductions for top projects.")
+            pause_and_return()
+        elif choice == "3":
+            print(f"\n{MAGENTA}[+] Submission Setup:{RESET}")
+            print("    1. Enroll on Lablab.ai")
+            print("    2. Import Severn: `from severn import trace`")
+            print("    3. Decorate tool calls with `@trace` & include `severn_traces.jsonl` in your repo.")
+            pause_and_return()
+        elif choice == "B":
+            break
+
+# -------------------------------------------------------------------------
+# ROADMAP & ADVANCED FEATURES MULTI-STEP
+# -------------------------------------------------------------------------
+def sub_menu_premium():
+    while True:
+        show_banner()
+        print(f"{MAGENTA}{BOLD}👑 ADVANCED ROADMAP & ENGINE SPECS (MULTI-STEP EXPLORER):{RESET}\n")
+        print(f"  {GREEN}[1]{RESET} {BOLD}Automated Self-Healing Retry Loop{RESET}")
+        print(f"  {CYAN}[2]{RESET} {BOLD}Zero-Dependency Telemetry Exporter{RESET}")
+        print(f"  {YELLOW}[3]{RESET} {BOLD}Founding Builder Foundation Access{RESET}")
+        print(f"  {RED}[B]{RESET} {BOLD}Back to Main Menu{RESET}\n")
+        
+        choice = input(f"{CYAN}{BOLD}Select option (1-3 or B): {RESET}").strip().upper()
+        
+        if choice == "1":
+            print(f"\n{GREEN}[+] Self-Healing Retries:{RESET}")
+            print("    Upcoming SDK releases will feature automatic retry loops for broken API calls,")
+            print("    sanitizing invalid JSON schemas before agent execution fails.")
+            pause_and_return()
+        elif choice == "2":
+            print(f"\n{CYAN}[+] Zero-Dependency Core:{RESET}")
+            print("    Built strictly with standard Python modules (json, functools, time, uuid).")
+            print("    Zero external library conflicts across Python 3.8+ environments.")
+            pause_and_return()
+        elif choice == "3":
+            print(f"\n{YELLOW}[+] Founding Builder Foundation:{RESET}")
+            print("    Early competition participants and top builders receive priority roadmap voting")
+            print("    and early access to enterprise telemetry scaling tools.")
+            pause_and_return()
+        elif choice == "B":
+            break
+
+# -------------------------------------------------------------------------
+# MAIN INTERACTIVE MENU LOOP
+# -------------------------------------------------------------------------
+def interactive_menu():
+    while True:
+        show_banner()
+        
+        total, passed, failed = get_trace_stats()
+        
+        print(f"{WHITE}{BOLD}📊 PUBLIC LIVE SESSION DASHBOARD (LOCAL TELEMETRY):{RESET}")
+        print(f"   {CYAN}Total Local Telemetry Records:{RESET} {WHITE}{total}{RESET}")
+        print(f"   {GREEN}Successfully Executed Steps:  {RESET} {WHITE}{passed}{RESET}")
+        print(f"   {RED}Caught Agent Loop Failures:   {RESET} {WHITE}{failed}{RESET}\n")
+        
+        print(f"{YELLOW}{BOLD}SELECT AN OPTION TO NAVIGATE SEVERN (1 - 7):{RESET}\n")
+        print(f"  {GREEN}[1]{RESET} {BOLD}Verify Active Trace Status{RESET}       - Check if local runtime engine is active")
+        print(f"  {CYAN}[2]{RESET} {BOLD}View Local Telemetry Database{RESET}    - Inspect raw `severn_traces.jsonl` export records")
+        print(f"  {TEAL}[3]{RESET} {BOLD}Agent Framework Topologies{RESET}   - Explore CrewAI, LangChain & AutoGen integration options")
+        print(f"  {YELLOW}[4]{RESET} {BOLD}Lablab.ai Hackathon Portal{RESET}       - Access multi-step AI Agent competition guides")
+        print(f"  {MAGENTA}[5]{RESET} {BOLD}Claim Premium SDK Access Perks{RESET}  - Explore future self-healing & framework features")
+        print(f"  {BLUE}[6]{RESET} {BOLD}Direct Founder & Community Support{RESET} - Connect via Discord (@severnteam)")
+        print(f"  {RED}[7]{RESET} {BOLD}Exit Severn Console{RESET}\n")
+        
+        choice = input(f"{CYAN}{BOLD}Enter your choice (1-7): {RESET}").strip()
+        
+        if choice == "1":
+            print(f"\n{GREEN}[+] Status: Severn Tracing Engine v0.1.0 is fully active and listening.{RESET}")
+            print(f"    Instructions: Place {BOLD}@trace{RESET} on top of any Python function or agent tool call to auto-capture telemetry.")
+            pause_and_return()
+            
+        elif choice == "2":
+            print(f"\n{YELLOW}[*] Reading local trace logs from severn_traces.jsonl...{RESET}")
+            log_path = "severn_traces.jsonl"
+            if os.path.exists(log_path):
+                with open(log_path, "r", encoding="utf-8") as f:
+                    lines = f.readlines()
+                    print(f"{GREEN}Found {len(lines)} total trace records stored locally on your machine:{RESET}\n")
+                    for line in lines[-5:]:
+                        print(f"  {CYAN}→{RESET} {line.strip()}")
+            else:
+                print(f"{YELLOW}[!] No local trace records found yet. Execute a test agent script decorated with @trace first!{RESET}")
+            pause_and_return()
+            
+        elif choice == "3":
+            sub_menu_agent_topology()
+
+        elif choice == "4":
+            sub_menu_hackathon()
+            
+        elif choice == "5":
+            sub_menu_premium()
+            
+        elif choice == "6":
+            blue_discord_art = f"""{BLUE}
+         ______
+      .-'      '-.
+     /            \\
+    |  ()      ()  |
+    |      __      |
+     \\            /
+      '-.______.-'
+            {RESET}"""
+            print(blue_discord_art)
+            print(f"{ORANGE}[💬] DIRECT FOUNDER & COMMUNITY SUPPORT:{RESET}")
+            print(f"    Have questions, need help configuring your trace setup, or want to report agent failure stress tests?")
+            print(f"    Reach out directly through our community channel:")
+            print(f"    - Discord Community Handle: {BOLD}@severnteam{RESET}")
+            print(f"    - Direct Founder Email Support: {BOLD}david@severn.dev{RESET}")
+            print(f"    - Mission Statement: Built by a 15-year-old solo founder to solve autonomous agent reliability forever.")
+            pause_and_return()
+            
+        elif choice == "7":
+            print(f"\n{YELLOW}Exiting Severn Console. Keep building exceptional autonomous systems!{RESET}\n")
+            sys.exit(0)
+
+if __name__ == "__main__":
+    interactive_menu()

severn/exporter.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+import atexit
+import json
+import os
+import queue
+import threading
+import time
+import urllib.request
+from typing import Any, Dict, Optional
+
+from . import __version__
+
+ENV_ENDPOINT = "SEVERN_ENDPOINT"
+ENV_API_KEY = "SEVERN_API_KEY"
+ENV_TIMEOUT = "SEVERN_TIMEOUT"
+
+DEFAULT_TIMEOUT = 2.0
+DEFAULT_QUEUE_SIZE = 1000
+DEFAULT_FLUSH_TIMEOUT = 2.0
+LOCAL_LOG_FILE = "severn_traces.jsonl"
+
+
+class Exporter:
+    def __init__(
+        self,
+        endpoint: Optional[str] = None,
+        timeout: Optional[float] = None,
+        api_key: Optional[str] = None,
+        max_queue: int = DEFAULT_QUEUE_SIZE,
+    ) -> None:
+        self._endpoint_override = endpoint
+        self._timeout_override = timeout
+        self._api_key_override = api_key
+        self._queue: "queue.Queue[Dict[str, Any]]" = queue.Queue(maxsize=max_queue)
+        self._thread: Optional[threading.Thread] = None
+        self._lock = threading.Lock()
+        self.dropped = 0
+
+    @property
+    def endpoint(self) -> Optional[str]:
+        value = self._endpoint_override or os.environ.get(ENV_ENDPOINT, "")
+        value = (value or "").strip()
+        if value.lower().startswith(("http://", "https://")):
+            return value
+        return None
+
+    @property
+    def timeout(self) -> float:
+        if self._timeout_override is not None:
+            candidate: Any = self._timeout_override
+        else:
+            candidate = os.environ.get(ENV_TIMEOUT, "")
+        try:
+            value = float(candidate)
+        except (TypeError, ValueError):
+            return DEFAULT_TIMEOUT
+        return value if value > 0 else DEFAULT_TIMEOUT
+
+    @property
+    def api_key(self) -> Optional[str]:
+        return self._api_key_override or os.environ.get(ENV_API_KEY) or None
+
+    def export(self, payload: Dict[str, Any]) -> bool:
+        try:
+            with open(LOCAL_LOG_FILE, "a", encoding="utf-8") as f:
+                f.write(json.dumps(payload, default=str) + "\n")
+        except Exception:
+            pass
+
+        try:
+            if self.endpoint is None:
+                return False
+            self._ensure_thread()
+            self._queue.put_nowait(payload)
+            return True
+        except queue.Full:
+            self.dropped += 1
+            return False
+        except Exception:
+            return False
+
+    def flush(self, timeout: float = DEFAULT_FLUSH_TIMEOUT) -> bool:
+        deadline = time.monotonic() + max(timeout, 0.0)
+        while self._queue.unfinished_tasks > 0:
+            if time.monotonic() >= deadline:
+                return False
+            time.sleep(0.01)
+        return True
+
+    def _ensure_thread(self) -> None:
+        thread = self._thread
+        if thread is not None and thread.is_alive():
+            return
+        with self._lock:
+            thread = self._thread
+            if thread is not None and thread.is_alive():
+                return
+            thread = threading.Thread(
+                target=self._run, name="severn-exporter", daemon=True
+            )
+            thread.start()
+            self._thread = thread
+
+    def _run(self) -> None:
+        while True:
+            payload = self._queue.get()
+            try:
+                self._send(payload)
+            except Exception:
+                pass
+            finally:
+                self._queue.task_done()
+
+    def _send(self, payload: Dict[str, Any]) -> None:
+        endpoint = self.endpoint
+        if endpoint is None:
+            return
+        body = json.dumps(payload, default=str).encode("utf-8")
+        headers = {
+            "Content-Type": "application/json",
+            "User-Agent": "severn-trace/" + __version__,
+        }
+        api_key = self.api_key
+        if api_key:
+            headers["Authorization"] = "Bearer " + api_key
+        request = urllib.request.Request(
+            endpoint, data=body, headers=headers, method="POST"
+        )
+        with urllib.request.urlopen(request, timeout=self.timeout) as response:
+            response.read(1024)
+
+
+_default_exporter = Exporter()
+
+
+def get_exporter() -> Exporter:
+    return _default_exporter
+
+
+def configure(
+    endpoint: Optional[str] = None,
+    timeout: Optional[float] = None,
+    api_key: Optional[str] = None,
+) -> Exporter:
+    exporter = _default_exporter
+    if endpoint is not None:
+        exporter._endpoint_override = endpoint
+    if timeout is not None:
+        exporter._timeout_override = timeout
+    if api_key is not None:
+        exporter._api_key_override = api_key
+    return exporter
+
+
+def export(payload: Dict[str, Any]) -> bool:
+    return _default_exporter.export(payload)
+
+
+def flush(timeout: float = DEFAULT_FLUSH_TIMEOUT) -> bool:
+    return _default_exporter.flush(timeout)
+
+
+def _flush_at_exit() -> None:
+    try:
+        _default_exporter.flush(DEFAULT_FLUSH_TIMEOUT)
+    except Exception:
+        pass
+
+
+atexit.register(_flush_at_exit)

severn/tracer.py

@@ -0,0 +1,433 @@
+from __future__ import annotations
+
+import functools
+import inspect
+import os
+import sys
+import time
+import traceback
+import uuid
+from contextvars import ContextVar
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, Iterable, Optional, TypeVar, Union
+
+from . import __version__
+from . import exporter as _exporter
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+SUCCESS = "SUCCESS"
+FAILED = "FAILED"
+
+_SENSITIVE_FRAGMENTS = (
+    "password",
+    "passwd",
+    "secret",
+    "token",
+    "api_key",
+    "apikey",
+    "authorization",
+    "credential",
+    "private_key",
+)
+_REDACTED = "***REDACTED***"
+_TERMINAL_PREVIEW_CHARS = 80
+
+_RESET = "\033[0m"
+_BOLD = "\033[1m"
+_DIM = "\033[2m"
+_RED = "\033[31m"
+_GREEN = "\033[32m"
+
+
+class _SpanContext:
+    __slots__ = ("trace_id", "span_id", "depth")
+
+    def __init__(self, trace_id: str, span_id: str, depth: int) -> None:
+        self.trace_id = trace_id
+        self.span_id = span_id
+        self.depth = depth
+
+
+_current_span: "ContextVar[Optional[_SpanContext]]" = ContextVar(
+    "severn_current_span", default=None
+)
+
+
+def _preview(value: Any, limit: int) -> str:
+    try:
+        text = repr(value)
+    except Exception:
+        text = "<unrepresentable %s>" % type(value).__name__
+    text = text.replace("\r", " ").replace("\n", " ")
+    if len(text) > limit:
+        extra = len(text) - limit
+        text = text[:limit] + "...(+%d chars)" % extra
+    return text
+
+
+def _is_sensitive(name: str, extra: frozenset) -> bool:
+    lowered = name.lower()
+    if lowered in extra:
+        return True
+    return any(fragment in lowered for fragment in _SENSITIVE_FRAGMENTS)
+
+
+def _capture_args(
+    signature: Optional[inspect.Signature],
+    args: tuple,
+    kwargs: dict,
+    limit: int,
+    redact: frozenset,
+) -> Dict[str, str]:
+    captured: Dict[str, str] = {}
+
+    def put(name: str, value: Any) -> None:
+        if _is_sensitive(name, redact):
+            captured[name] = _REDACTED
+        else:
+            captured[name] = _preview(value, limit)
+
+    bound = None
+    if signature is not None:
+        try:
+            bound = signature.bind_partial(*args, **kwargs)
+        except TypeError:
+            bound = None
+
+    if bound is None:
+        for index, value in enumerate(args):
+            put("arg%d" % index, value)
+        for key, value in kwargs.items():
+            put(str(key), value)
+        return captured
+
+    for name, value in bound.arguments.items():
+        kind = signature.parameters[name].kind  # type: ignore[union-attr]
+        if kind is inspect.Parameter.VAR_KEYWORD and isinstance(value, dict):
+            for key, item in value.items():
+                put(str(key), item)
+        elif name in ("self", "cls"):
+            continue
+        else:
+            put(name, value)
+    return captured
+
+
+def _format_duration(ms: float) -> str:
+    if ms < 1000:
+        return "%.1fms" % ms
+    return "%.2fs" % (ms / 1000.0)
+
+
+def _error_type_name(exc: BaseException) -> str:
+    cls = type(exc)
+    if cls.__module__ in ("builtins", "__main__"):
+        return cls.__qualname__
+    return "%s.%s" % (cls.__module__, cls.__qualname__)
+
+
+def _color_enabled(stream: Any) -> bool:
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("FORCE_COLOR"):
+        return True
+    try:
+        return bool(stream.isatty())
+    except Exception:
+        return False
+
+
+def _symbols(stream: Any):
+    encoding = getattr(stream, "encoding", None) or "ascii"
+    try:
+        "✔✘→".encode(encoding)
+        return "✔", "✘", "→"
+    except Exception:
+        return "OK", "FAIL", "->"
+
+
+def _quiet(override: Optional[bool]) -> bool:
+    if override is not None:
+        return override
+    return os.environ.get("SEVERN_QUIET", "").strip().lower() in (
+        "1",
+        "true",
+        "yes",
+        "on",
+    )
+
+
+class _Config:
+    __slots__ = (
+        "step",
+        "signature",
+        "capture_args",
+        "capture_output",
+        "max_preview",
+        "quiet",
+        "show_traceback",
+        "redact",
+    )
+
+    def __init__(
+        self,
+        step: str,
+        signature: Optional[inspect.Signature],
+        capture_args: bool,
+        capture_output: bool,
+        max_preview: int,
+        quiet: Optional[bool],
+        show_traceback: bool,
+        redact: frozenset,
+    ) -> None:
+        self.step = step
+        self.signature = signature
+        self.capture_args = capture_args
+        self.capture_output = capture_output
+        self.max_preview = max_preview
+        self.quiet = quiet
+        self.show_traceback = show_traceback
+        self.redact = redact
+
+
+class _Span:
+    def __init__(self, config: _Config, args: tuple, kwargs: dict) -> None:
+        self.config = config
+        self.args_snapshot: Dict[str, str] = {}
+        self.trace_id = ""
+        self.span_id = ""
+        self.parent_span_id: Optional[str] = None
+        self.depth = 0
+        self.timestamp = ""
+        self._token: Any = None
+        self._t0 = time.perf_counter()
+        try:
+            if config.capture_args:
+                self.args_snapshot = _capture_args(
+                    config.signature, args, kwargs, config.max_preview, config.redact
+                )
+            parent = _current_span.get()
+            self.trace_id = parent.trace_id if parent else uuid.uuid4().hex
+            self.span_id = uuid.uuid4().hex[:16]
+            self.parent_span_id = parent.span_id if parent else None
+            self.depth = parent.depth + 1 if parent else 0
+            self.timestamp = datetime.now(timezone.utc).isoformat(
+                timespec="milliseconds"
+            )
+            self._token = _current_span.set(
+                _SpanContext(self.trace_id, self.span_id, self.depth)
+            )
+        except Exception:
+            pass
+        self._t0 = time.perf_counter()
+
+    def succeed(self, result: Any) -> None:
+        latency_ms = (time.perf_counter() - self._t0) * 1000.0
+        self._finish(SUCCESS, latency_ms, result=result, exc=None)
+
+    def fail(self, exc: BaseException) -> None:
+        latency_ms = (time.perf_counter() - self._t0) * 1000.0
+        self._finish(FAILED, latency_ms, result=None, exc=exc)
+
+    def _finish(
+        self,
+        status: str,
+        latency_ms: float,
+        result: Any,
+        exc: Optional[BaseException],
+    ) -> None:
+        try:
+            if self._token is not None:
+                try:
+                    _current_span.reset(self._token)
+                except ValueError:
+                    pass
+                self._token = None
+
+            config = self.config
+            output_preview: Optional[str] = None
+            error: Optional[Dict[str, str]] = None
+
+            if exc is None:
+                if config.capture_output:
+                    output_preview = _preview(result, config.max_preview)
+            else:
+                tb = exc.__traceback__
+                inner = tb.tb_next if tb is not None and tb.tb_next is not None else tb
+                try:
+                    message = str(exc)
+                except Exception:
+                    message = "<unprintable %s>" % type(exc).__name__
+                error = {
+                    "type": _error_type_name(exc),
+                    "message": message,
+                    "stacktrace": "".join(
+                        traceback.format_exception(type(exc), exc, inner)
+                    ),
+                }
+
+            payload: Dict[str, Any] = {
+                "sdk": "severn-trace",
+                "sdk_version": __version__,
+                "trace_id": self.trace_id,
+                "span_id": self.span_id,
+                "parent_span_id": self.parent_span_id,
+                "step": config.step,
+                "status": status,
+                "timestamp": self.timestamp,
+                "latency_ms": round(latency_ms, 3),
+                "args": self.args_snapshot if config.capture_args else None,
+                "output_preview": output_preview,
+                "error": error,
+            }
+
+            self._print(status, latency_ms, output_preview, error, exc)
+            _exporter.export(payload)
+        except Exception:
+            pass
+
+    def _print(
+        self,
+        status: str,
+        latency_ms: float,
+        output_preview: Optional[str],
+        error: Optional[Dict[str, str]],
+        exc: Optional[BaseException],
+    ) -> None:
+        config = self.config
+        if _quiet(config.quiet):
+            return
+        stream = sys.stderr
+        use_color = _color_enabled(stream)
+        ok_sym, fail_sym, arrow = _symbols(stream)
+
+        def paint(code: str, text: str) -> str:
+            return code + text + _RESET if use_color else text
+
+        indent = "  " * self.depth
+        duration = _format_duration(latency_ms)
+        lines = []
+
+        if status == SUCCESS:
+            head = "%s%s %s  %s" % (
+                indent,
+                paint(_GREEN, ok_sym),
+                paint(_BOLD, config.step),
+                paint(_DIM, duration),
+            )
+            if output_preview is not None:
+                head += "  %s %s" % (
+                    paint(_DIM, arrow),
+                    paint(_DIM, _truncate(output_preview, _TERMINAL_PREVIEW_CHARS)),
+                )
+            lines.append(head)
+        else:
+            assert error is not None
+            lines.append(
+                "%s%s %s  %s  %s  %s: %s"
+                % (
+                    indent,
+                    paint(_RED, fail_sym),
+                    paint(_BOLD, config.step),
+                    paint(_RED, "FAILED"),
+                    paint(_DIM, duration),
+                    paint(_RED, error["type"]),
+                    _truncate(error["message"].replace("\n", " "), 200),
+                )
+            )
+            location = _innermost_location(exc)
+            if location:
+                lines.append("%s  %s" % (indent, paint(_DIM, "at " + location)))
+            if config.show_traceback:
+                for raw in error["stacktrace"].rstrip().splitlines():
+                    lines.append("%s  %s" % (indent, paint(_DIM, raw)))
+
+        try:
+            stream.write("\n".join(lines) + "\n")
+            stream.flush()
+        except Exception:
+            pass
+
+
+def _truncate(text: str, limit: int) -> str:
+    if len(text) <= limit:
+        return text
+    return text[: max(limit - 3, 0)] + "..."
+
+
+def _innermost_location(exc: Optional[BaseException]) -> Optional[str]:
+    if exc is None or exc.__traceback__ is None:
+        return None
+    try:
+        frames = traceback.extract_tb(exc.__traceback__)
+        if not frames:
+            return None
+        frame = frames[-1]
+        return "%s:%s in %s" % (frame.filename, frame.lineno, frame.name)
+    except Exception:
+        return None
+
+
+def trace(
+    func: Optional[F] = None,
+    *,
+    name: Optional[str] = None,
+    capture_args: bool = True,
+    capture_output: bool = True,
+    max_preview: int = 200,
+    quiet: Optional[bool] = None,
+    show_traceback: bool = False,
+    redact: Iterable[str] = (),
+) -> Union[F, Callable[[F], F]]:
+    redact_names = frozenset(str(item).lower() for item in redact)
+
+    def decorator(target: F) -> F:
+        try:
+            signature: Optional[inspect.Signature] = inspect.signature(target)
+        except (TypeError, ValueError):
+            signature = None
+
+        config = _Config(
+            step=name or getattr(target, "__qualname__", None) or repr(target),
+            signature=signature,
+            capture_args=capture_args,
+            capture_output=capture_output,
+            max_preview=max(int(max_preview), 1),
+            quiet=quiet,
+            show_traceback=show_traceback,
+            redact=redact_names,
+        )
+
+        if inspect.iscoroutinefunction(target):
+            @functools.wraps(target)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                span = _Span(config, args, kwargs)
+                try:
+                    result = await target(*args, **kwargs)
+                except BaseException as exc:
+                    span.fail(exc)
+                    raise
+                span.succeed(result)
+                return result
+
+            async_wrapper.__severn_traced__ = True  # type: ignore[attr-defined]
+            return async_wrapper  # type: ignore[return-value]
+
+        @functools.wraps(target)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            span = _Span(config, args, kwargs)
+            try:
+                result = target(*args, **kwargs)
+            except BaseException as exc:
+                span.fail(exc)
+                raise
+            span.succeed(result)
+            return result
+
+        sync_wrapper.__severn_traced__ = True  # type: ignore[attr-defined]
+        return sync_wrapper  # type: ignore[return-value]
+
+    if func is not None:
+        return decorator(func)
+    return decorator

severn_trace-0.1.0.dist-info/METADATA

@@ -0,0 +1,3 @@
+Metadata-Version: 2.4
+Name: severn-trace
+Version: 0.1.0

severn_trace-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+severn/__init__.py,sha256=Dgj5UM_OiC4vuU4nwSTccMns6HQ6CmH9lCz4dUgx5Ww,348
+severn/cli.py,sha256=31zB_9BzD-1hxVJB-Q-u8FMQhw7Vf_PRUHXVvzku8M0,12484
+severn/exporter.py,sha256=wzaUiiYwcx2reesrqBMTP2nmR8NDNPIjYTw8g5AH3nA,4898
+severn/tracer.py,sha256=CEA5V9xVEjw9nBBmkDoRa3eUmyVAd3fnAgZmcAg7P9w,12957
+severn_trace-0.1.0.dist-info/METADATA,sha256=hIwPPxrLMmpidkdm7RuHFTnUg-xUagW7qNCVviGgyo8,56
+severn_trace-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+severn_trace-0.1.0.dist-info/entry_points.txt,sha256=GtvAEwz1EapkVVNQ80181vrFaaK0ougC2v1B5UuDZsc,55
+severn_trace-0.1.0.dist-info/top_level.txt,sha256=lNiy40FjePfjV_RUlCZOkyDencIbCJunDncFmLtJRcc,7
+severn_trace-0.1.0.dist-info/RECORD,,

severn_trace-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

severn_trace-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+severn = severn.cli:interactive_menu

severn_trace-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+severn