1"use strict";(globalThis.webpackChunkwebsite=globalThis.webpackChunkwebsite||[]).push([[6064],{80992(e,n,r){r.r(n),r.d(n,{assets:()=>t,contentTitle:()=>i,default:()=>a,frontMatter:()=>l,metadata:()=>s,toc:()=>o});const s=JSON.parse('{"id":"observe/api/python-sdk","title":"Python SDK Reference","description":"Complete API reference for all public classes, functions, and types in the waxell-observe Python package.","source":"@site/docs/observe/api/python-sdk.md","sourceDirName":"observe/api","slug":"/observe/api/python-sdk","permalink":"/docs/observe/api/python-sdk","draft":false,"unlisted":false,"editUrl":"https://gitlab.com/waxell/agentforge/-/edit/main/website/docs/observe/api/python-sdk.md","tags":[],"version":"current","sidebarPosition":2,"frontMatter":{"sidebar_position":2,"title":"Python SDK Reference","description":"Complete API reference for all public classes, functions, and types in the waxell-observe Python package.","keywords":["waxell","observe","python","sdk","api reference","documentation"]},"sidebar":"observeSidebar","previous":{"title":"REST API Reference","permalink":"/docs/observe/api/endpoints"}}');var d=r(74848),c=r(28453);const l={sidebar_position:2,title:"Python SDK Reference",description:"Complete API reference for all public classes, functions, and types in the waxell-observe Python package.",keywords:["waxell","observe","python","sdk","api reference","documentation"]},i="Python SDK Reference",t={},o=[{value:"init",id:"init",level:2},{value:"shutdown",id:"shutdown",level:2},{value:"generate_session_id",id:"generate_session_id",level:2},{value:"Top-Level Convenience Functions",id:"top-level-convenience-functions",level:2},{value:"tag",id:"tag",level:3},{value:"metadata",id:"metadata",level:3},{value:"score",id:"score",level:3},{value:"decide",id:"decide",level:3},{value:"step",id:"step",level:3},{value:"reason",id:"reason",level:3},{value:"retrieve",id:"retrieve",level:3},{value:"retry",id:"retry",level:3},{value:"get_context",id:"get_context",level:3},{value:"input",id:"input",level:3},{value:"human_turn",id:"human_turn",level:3},{value:"human_interaction",id:"human_interaction",level:3},{value:"user_message",id:"user_message",level:3},{value:"agent_response",id:"agent_response",level:3},{value:"communication",id:"communication",level:3},{value:"approval_request",id:"approval_request",level:3},{value:"approval_response",id:"approval_response",level:3},{value:"flush",id:"flush",level:3},{value:"flush_sync",id:"flush_sync",level:3},{value:"diagnose",id:"diagnose",level:3},{value:"prompt_approval",id:"prompt_approval",level:3},{value:"auto_approve / auto_deny",id:"auto_approve--auto_deny",level:3},{value:"Drop-in Imports",id:"drop-in-imports",level:2},{value:"Instrumentation Functions",id:"instrumentation-functions",level:2},{value:"instrument_all",id:"instrument_all",level:3},{value:"uninstrument_all",id:"uninstrument_all",level:3},{value:"OpenTelemetry Functions",id:"opentelemetry-functions",level:2},{value:"init_tracing",id:"init_tracing",level:3},{value:"flush_tracing",id:"flush_tracing",level:3},{value:"shutdown_tracing",id:"shutdown_tracing",level:3},{value:"WaxellObserveClient",id:"waxellobserveclient",level:2},{value:"Constructor",id:"constructor",level:3},{value:"Class Methods",id:"class-methods",level:3},{value:"configure",id:"configure",level:4},{value:"get_config",id:"get_config",level:4},{value:"is_configured",id:"is_configured",level:4},{value:"Async Methods",id:"async-methods",level:3},{value:"start_run",id:"start_run",level:4},{value:"complete_run",id:"complete_run",level:4},{value:"record_llm_calls",id:"record_llm_calls",level:4},{value:"record_steps",id:"record_steps",level:4},{value:"record_scores",id:"record_scores",level:4},{value:"get_prompt",id:"get_prompt",level:4},{value:"check_policy",id:"check_policy",level:4},{value:"record_events",id:"record_events",level:4},{value:"close",id:"close",level:4},{value:"Sync Methods",id:"sync-methods",level:3},{value:"WaxellContext",id:"waxellcontext",level:2},{value:"Constructor",id:"constructor-1",level:3},{value:"Usage",id:"usage",level:3},{value:"Lifecycle",id:"lifecycle",level:3},{value:"Methods",id:"methods",level:3},{value:"record_llm_call",id:"record_llm_call",level:4},{value:"record_step",id:"record_step",level:4},{value:"set_result",id:"set_result",level:4},{value:"record_score",id:"record_score",level:4},{value:"set_tag",id:"set_tag",level:4},{value:"set_metadata",id:"set_metadata",level:4},{value:"Behavior Tracking Methods",id:"behavior-tracking-methods",level:4},{value:"record_tool_call",id:"record_tool_call",level:4},{value:"record_retrieval",id:"record_retrieval",level:4},{value:"record_decision",id:"record_decision",level:4},{value:"record_reasoning",id:"record_reasoning",level:4},{value:"record_retry",id:"record_retry",level:4},{value:"check_policy / check_policy_sync",id:"check_policy--check_policy_sync",level:4},{value:"Properties",id:"properties",level:3},{value:"@observe / @waxell_agent",id:"observe--waxell_agent",level:2},{value:"Signature",id:"signature",level:3},{value:"Context Injection",id:"context-injection",level:3},{value:"Example",id:"example",level:3},{value:"Behavior",id:"behavior",level:3},{value:"@tool",id:"tool",level:2},{value:"Signature",id:"signature-1",level:3},{value:"@decision",id:"decision",level:2},{value:"Signature",id:"signature-2",level:3},{value:"@retrieval",id:"retrieval",level:2},{value:"Signature",id:"signature-3",level:3},{value:"@reasoning_dec",id:"reasoning_dec",level:2},{value:"Signature",id:"signature-4",level:3},{value:"@retry_dec",id:"retry_dec",level:2},{value:"Signature",id:"signature-5",level:3},{value:"@step_dec",id:"step_dec",level:2},{value:"Signature",id:"signature-6",level:3},{value:"WaxellLangChainHandler",id:"waxelllangchainhandler",level:2},{value:"Signature",id:"signature-7",level:3},{value:"Instance Methods",id:"instance-methods",level:3},{value:"flush",id:"flush-1",level:4},{value:"flush_sync",id:"flush_sync-1",level:4},{value:"Instance Properties",id:"instance-properties",level:3},{value:"Captured Callbacks",id:"captured-callbacks",level:3},{value:"Types",id:"types",level:2},{value:"RunInfo",id:"runinfo",level:3},{value:"RunCompleteResult",id:"runcompleteresult",level:3},{value:"PolicyCheckResult",id:"policycheckresult",level:3}
1,{value:"LlmCallInfo",id:"llmcallinfo",level:3},{value:"PromptInfo",id:"promptinfo",level:3},{value:"compile",id:"compile",level:4},{value:"ObserveConfig",id:"observeconfig",level:3},{value:"ApprovalDecision",id:"approvaldecision",level:3},{value:"HumanTurn",id:"humanturn",level:3},{value:"Errors",id:"errors",level:2},{value:"ObserveError",id:"observeerror",level:3},{value:"PolicyViolationError",id:"policyviolationerror",level:3},{value:"ConfigurationError",id:"configurationerror",level:3},{value:"Functions",id:"functions",level:2},{value:"estimate_cost",id:"estimate_cost",level:3},{value:"Configuration Resolution",id:"configuration-resolution",level:2},{value:"Next Steps",id:"next-steps",level:2}];function h(e){const n={a:"a",admonition:"admonition",code:"code",h1:"h1",h2:"h2",h3:"h3",h4:"h4",header:"header",hr:"hr",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,c.R)(),...e.components};return(0,d.jsxs)(d.Fragment,{children:[(0,d.jsx)(n.header,{children:(0,d.jsx)(n.h1,{id:"python-sdk-reference",children:"Python SDK Reference"})}),"\n",(0,d.jsxs)(n.p,{children:["This is the complete API reference for the ",(0,d.jsx)(n.code,{children:"waxell-observe"})," package. All public symbols are exported from the top-level ",(0,d.jsx)(n.code,{children:"waxell_observe"})," module."]}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"from waxell_observe import (\n # Top-level functions\n init,\n shutdown,\n generate_session_id,\n # Decorators\n observe, # Agent run decorator (alias for waxell_agent)\n waxell_agent, # Original agent decorator (identical to observe)\n tool, # @tool decorator\n decision, # @decision decorator\n retrieval, # @retrieval decorator\n reasoning_dec, # @reasoning decorator\n retry_dec, # @retry decorator\n step_dec, # @step decorator\n # Convenience functions (work within active context)\n tag,\n metadata,\n score,\n decide,\n step,\n reason,\n retrieve,\n retry,\n get_context,\n # Human-in-the-loop\n input, # Drop-in replacement for input()\n human_turn, # Context manager for non-terminal channels\n human_interaction, # One-shot recording\n # Approval handlers\n prompt_approval, # Terminal Y/N prompt\n auto_approve, # Always approve (testing)\n auto_deny, # Always deny (testing)\n # Core classes\n WaxellObserveClient,\n ObserveConfig,\n WaxellContext,\n HumanTurn,\n # Types\n ApprovalDecision,\n LlmCallInfo,\n PolicyCheckResult,\n PromptGuardResult,\n RunCompleteResult,\n RunInfo,\n # Errors\n ConfigurationError,\n ObserveError,\n PolicyViolationError,\n PromptGuardError,\n)\n"})}),"\n",(0,d.jsx)(n.hr,{}),"\n",(0,d.jsx)(n.h2,{id:"init",children:"init"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'import waxell_observe\n\nwaxell_observe.init(\n api_key: str = "",\n api_url: str = "",\n capture_content: bool = False,\n instrument: list[str] | None = None,\n exclude: list[str] | None = None,\n instrument_infra: bool = True,\n infra_libraries: list[str] | None = None,\n infra_exclude: list[str] | None = None,\n resource_attributes: dict | None = None,\n debug: bool = False,\n prompt_guard: bool = False,\n prompt_guard_server: bool = False,\n prompt_guard_action: str = "block",\n on_policy_block: Callable | None = None,\n) -> None\n'})}),"\n",(0,d.jsx)(n.p,{children:"One-line initialization for waxell-observe. This single call configures the HTTP client, initializes OTel tracing (if installed), and auto-instruments installed LLM libraries."}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"api_key"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsxs)(n.td,{children:["Waxell API key (",(0,d.jsx)(n.code,{children:"wax_sk_..."}),"). Falls back to ",(0,d.jsx)(n.code,{children:"WAXELL_API_KEY"})," env var"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"api_url"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsxs)(n.td,{children:["Waxell API URL. Falls back to ",(0,d.jsx)(n.code,{children:"WAXELL_API_URL"})," env var"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"capture_content"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"bool"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"False"})}),(0,d.jsx)(n.td,{children:"Include prompt/response content in OTel traces"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"instrument"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"list[str] | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsxs)(n.td,{children:["Libraries to auto-instrument (e.g. ",(0,d.jsx)(n.code,{children:'["openai", "anthropic"]'}),"). ",(0,d.jsx)(n.code,{children:"None"})," means auto-detect all installed libraries"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"exclude"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"list[str] | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsxs)(n.td,{children:["Skip these libraries during auto-instrumentation (e.g. ",(0,d.jsx)(n.code,{children:'["litellm", "mcp"]'}),"). Falls back to ",(0,d.jsx)(n.code,{children:"WAXELL_EXCLUDE"})," env var (comma-delimited). Takes precedence over ",(0,d.jsx)(n.code,{children:"instrument"})]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"instrument_infra"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"bool"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"True"})}),(0,d.jsxs)(n.td,{children:["Enable auto-instrumentation of infrastru
1cture libraries (HTTP clients, databases, caches, queues). Falls back to ",(0,d.jsx)(n.code,{children:"WAXELL_INSTRUMENT_INFRA"})," env var"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"infra_libraries"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"list[str] | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsxs)(n.td,{children:["Only instrument these specific infra libraries (e.g. ",(0,d.jsx)(n.code,{children:'["redis", "httpx"]'}),"). ",(0,d.jsx)(n.code,{children:"None"})," means auto-detect all"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"infra_exclude"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"list[str] | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsxs)(n.td,{children:["Instrument all infra libraries except these (e.g. ",(0,d.jsx)(n.code,{children:'["celery", "grpc"]'}),"). Falls back to ",(0,d.jsx)(n.code,{children:"WAXELL_INFRA_EXCLUDE"})," env var (comma-delimited)"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"resource_attributes"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"dict | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsxs)(n.td,{children:["Custom OTel resource attributes applied to all spans (e.g. ",(0,d.jsx)(n.code,{children:'{"deployment.environment": "production"}'}),")"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"debug"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"bool"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"False"})}),(0,d.jsx)(n.td,{children:"Enable debug logging and console span export"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"prompt_guard"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"bool"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"False"})}),(0,d.jsxs)(n.td,{children:["Enable client-side prompt guard (PII, credential, injection detection). Falls back to ",(0,d.jsx)(n.code,{children:"WAXELL_PROMPT_GUARD"})," env var"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"prompt_guard_server"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"bool"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"False"})}),(0,d.jsxs)(n.td,{children:["Also check server-side guard service (ML-powered via Presidio + HuggingFace). Falls back to ",(0,d.jsx)(n.code,{children:"WAXELL_PROMPT_GUARD_SERVER"})," env var"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"prompt_guard_action"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'"block"'})}),(0,d.jsxs)(n.td,{children:["Action on violations: ",(0,d.jsx)(n.code,{children:'"block"'})," (raise error), ",(0,d.jsx)(n.code,{children:'"warn"'})," (log and continue), ",(0,d.jsx)(n.code,{children:'"redact"'})," (replace with ",(0,d.jsx)(n.code,{children:"##TYPE##"}),"). Falls back to ",(0,d.jsx)(n.code,{children:"WAXELL_PROMPT_GUARD_ACTION"})," env var"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"on_policy_block"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"Callable | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsxs)(n.td,{children:["Default handler for all contexts when a policy blocks. Receives ",(0,d.jsx)(n.code,{children:"PolicyViolationError"}),", returns ",(0,d.jsx)(n.code,{children:"ApprovalDecision"}),". Built-in: ",(0,d.jsx)(n.code,{children:"prompt_approval"}),", ",(0,d.jsx)(n.code,{children:"auto_approve"}),", ",(0,d.jsx)(n.code,{children:"auto_deny"})]})]})]})]}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Behavior:"})}),"\n",(0,d.jsxs)(n.ul,{children:["\n",(0,d.jsxs)(n.li,{children:["Checks the ",(0,d.jsx)(n.code,{children:"WAXELL_OBSERVE"})," environment variable kill switch first. If set to ",(0,d.jsx)(n.code,{children:'"false"'}),", ",(0,d.jsx)(n.code,{children:'"0"'}),", or ",(0,d.jsx)(n.code,{children:'"no"'}),", initialization is skipped entirely."]}),"\n",(0,d.jsxs)(n.li,{children:["Idempotent: calling ",(0,d.jsx)(n.code,{children:"init()"})," multiple times is safe. Only the first call takes effect."]}),"\n",(0,d.jsx)(n.li,{children:"OTel tracing failure does not block the HTTP path. If tracing initialization fails, a warning is logged and the HTTP-based telemetry continues to work."}),"\n",(0,d.jsx)(n.li,{children:"Auto-instrumentation failure does not block manual tracing."}),"\n"]}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'import waxell_observe\n\n# Minimal setup -- auto-detects URL from env, instruments all installed libraries\nwaxell_observe.init(api_key="wax_sk_abc123")\n\n# Full control\nwaxell_observe.init(\n api_key="wax_sk_abc123",\n api_url="https://acme.waxell.dev",\n capture_content=True,\n instrument=["openai", "anthropic"],\n debug=True,\n)\n'})}),"\n",(0,d.jsx)(n.hr,{}),"\n",(0,d.jsx)(n.h2,{id:"shutdown",children:"shutdown"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"import waxell_observe\n\nwaxell_observe.shutdown() -> None\n"})}),"\n",(0,d.jsx)(n.p,{children:"Shut down waxell-observe: flush pending traces and remove auto-instrumentation."}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Behavior:"})}),"\n",(0,d.jsxs)(n.ul,{children:["\n",(0,d.jsxs)(n.li,{children:["Calls ",(0,d.jsx)(n.code,{children:"shutdown_tracing()"})," to flush the OTel span processor and shut down the TracerProvider."]}),"\n",(0,d.jsxs)(n.li,{children:["Calls ",(0,d.jsx)(n.code,{children:"uninstrument_all()"})," to remove monkey-patches from instrumented libraries."]}),"\n",(0,d.jsxs)(n.li,{children:["Resets the internal ",(0,d.jsx)(n.code,{children:"_initialized"})," flag so ",(0,d.jsx)(n.code,{children:"init()"})," can be called again."]}),"\n",(0,d.jsxs)(n.li,{children:["Safe to call even if ",(0,d.jsx)(n.code,{children:"init()"})," was never called."]}),"\n"]}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'import waxell_observe\nimport atexit\n\nwaxell_observe.init(api_key="wax_sk_abc123")\natexit.register(waxell_observe.shutdown)\n'})}),"\n",(0,d.jsx)(n.hr,{}),"\n",(0,d.jsx)(n.h2,{id:"generate_session_id",children:"generate_session_id"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"from waxell_observe import generate_session_id\n\ngenerate_session_id() -> str\n"})}),"\n",(0,d.jsx)(n.p,{children:"Generate a random session ID for grouping related runs."}),"\n",(0,d.jsxs)(n.p,{children:[(0,d.jsx)(n.strong,{children:"Returns:"}
1)," A string in the format ",(0,d.jsx)(n.code,{children:"sess_"})," followed by 16 hex characters (e.g. ",(0,d.jsx)(n.code,{children:"sess_a1b2c3d4e5f6g7h8"}),")."]}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'from waxell_observe import generate_session_id, WaxellContext\n\nsession = generate_session_id()\n\nasync with WaxellContext(agent_name="agent-1", session_id=session) as ctx:\n ...\n\nasync with WaxellContext(agent_name="agent-2", session_id=session) as ctx:\n ...\n'})}),"\n",(0,d.jsx)(n.hr,{}),"\n",(0,d.jsx)(n.h2,{id:"top-level-convenience-functions",children:"Top-Level Convenience Functions"}),"\n",(0,d.jsxs)(n.p,{children:["These functions operate on the current ",(0,d.jsx)(n.code,{children:"WaxellContext"})," in scope. They are no-ops when called outside of an active context, making them safe to use in code that may or may not be wrapped by ",(0,d.jsx)(n.code,{children:"@observe"})," or ",(0,d.jsx)(n.code,{children:"WaxellContext"}),"."]}),"\n",(0,d.jsx)(n.h3,{id:"tag",children:"tag"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"import waxell_observe\n\nwaxell_observe.tag(key: str, value: str) -> None\n"})}),"\n",(0,d.jsx)(n.p,{children:"Set a searchable tag on the current context. No-op if no context is active."}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'from waxell_observe import observe\nimport waxell_observe\n\n@observe(agent_name="my-agent")\nasync def run_agent(query: str) -> str:\n waxell_observe.tag("environment", "production")\n waxell_observe.tag("pipeline", "rag-v2")\n return await process(query)\n'})}),"\n",(0,d.jsx)(n.h3,{id:"metadata",children:"metadata"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"import waxell_observe\n\nwaxell_observe.metadata(key: str, value: Any) -> None\n"})}),"\n",(0,d.jsx)(n.p,{children:"Set metadata on the current context. Values can be any JSON-serializable type. No-op if no context is active."}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'waxell_observe.metadata("model_version", "gpt-4-turbo")\nwaxell_observe.metadata("config", {"temperature": 0.7})\n'})}),"\n",(0,d.jsx)(n.h3,{id:"score",children:"score"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'import waxell_observe\n\nwaxell_observe.score(\n name: str,\n value: float | str | bool,\n data_type: str = "numeric",\n comment: str = "",\n) -> None\n'})}),"\n",(0,d.jsx)(n.p,{children:"Record a score on the current context. No-op if no context is active."}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"name"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsx)(n.td,{children:"Score name"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"value"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"float | str | bool"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsx)(n.td,{children:"Score value"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"data_type"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'"numeric"'})}),(0,d.jsxs)(n.td,{children:[(0,d.jsx)(n.code,{children:'"numeric"'}),", ",(0,d.jsx)(n.code,{children:'"categorical"'}),", or ",(0,d.jsx)(n.code,{children:'"boolean"'})]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"comment"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"Optional comment"})]})]})]}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'waxell_observe.score("relevance", 0.95)\nwaxell_observe.score("helpful", True, data_type="boolean")\nwaxell_observe.score("category", "informational", data_type="categorical")\n'})}),"\n",(0,d.jsx)(n.h3,{id:"decide",children:"decide"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'import waxell_observe\n\nwaxell_observe.decide(\n name: str,\n chosen: str,\n options: list[str] | None = None,\n reasoning: str = "",\n confidence: float | None = None,\n) -> None\n'})}),"\n",(0,d.jsx)(n.p,{children:"Record a decision on the current context. No-op if no context is active."}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"name"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsx)(n.td,{children:"Decision name"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"chosen"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsx)(n.td,{children:"The selected option"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"options"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"list[str] | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Available choices"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"reasoning"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"Why this option was chosen"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"confidence"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"float | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Confidence score (0.0-1.0)"})]})]})]}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'waxell_observe.decide(\n "route_query",\n chosen="semantic_search",\n options=["semantic", "keyword", "hybrid"],\n reasoning="Query contains
1natural language phrasing",\n confidence=0.9,\n)\n'})}),"\n",(0,d.jsx)(n.h3,{id:"step",children:"step"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"waxell_observe.step(name: str, output: dict | None = None) -> None\n"})}),"\n",(0,d.jsx)(n.p,{children:"Record an execution step on the current context. No-op if no context is active."}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"name"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsx)(n.td,{children:"Step name"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"output"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"dict | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Step output data"})]})]})]}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'waxell_observe.step("preprocessing", output={"tokens": 150, "language": "en"})\nwaxell_observe.step("validation") # output is optional\n'})}),"\n",(0,d.jsx)(n.h3,{id:"reason",children:"reason"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'waxell_observe.reason(\n step: str,\n thought: str,\n evidence: list[str] | None = None,\n conclusion: str = "",\n) -> None\n'})}),"\n",(0,d.jsx)(n.p,{children:"Record a reasoning step on the current context. No-op if no context is active."}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"step"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsx)(n.td,{children:"Reasoning step name"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"thought"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsx)(n.td,{children:"The reasoning thought process"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"evidence"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"list[str] | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Supporting evidence"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"conclusion"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"Final conclusion"})]})]})]}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'waxell_observe.reason(\n "source_evaluation",\n thought="Document A is from a peer-reviewed journal",\n evidence=["Published 2024", "Cited 45 times"],\n conclusion="High reliability source",\n)\n'})}),"\n",(0,d.jsx)(n.h3,{id:"retrieve",children:"retrieve"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'waxell_observe.retrieve(\n query: str,\n documents: list[dict],\n source: str = "",\n scores: list[float] | None = None,\n) -> None\n'})}),"\n",(0,d.jsx)(n.p,{children:"Record a retrieval operation on the current context. No-op if no context is active."}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"query"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsx)(n.td,{children:"The search query"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"documents"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"list[dict]"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsx)(n.td,{children:"Retrieved documents"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"source"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"Data source name"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"scores"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"list[float] | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Relevance scores"})]})]})]}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'waxell_observe.retrieve(\n query="AI safety best practices",\n documents=[{"id": "doc1", "title": "Safety Guide"}],\n source="pinecone",\n scores=[0.95],\n)\n'})}),"\n",(0,d.jsx)(n.h3,{id:"retry",children:"retry"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'waxell_observe.retry(\n attempt: int,\n reason: str,\n strategy: str = "retry",\n original_error: str = "",\n fallback_to: str = "",\n) -> None\n'})}),"\n",(0,d.jsx)(n.p,{children:"Record a retry/fallback event on the current context. No-op if no context is active."}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"attempt"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"int"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsx)(n.td,{children:"Attempt number (1-indexed)"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"reason"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsx)(n.td,{children:"Why the retry occurred"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"strategy"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'"retry"'})}),(0,d.jsxs)(n.td,{children:["Strategy: ",(0,d.jsx)(n.code,{children:'"retry"'}),", ",(0,d.jsx)(n.code,{children:'"fallback"'}),", ",(0,d.jsx)(n.code,{children:'"circuit_break"'})]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"original_error"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"Error that triggered the retry"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"fallback_to"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"Fallback target name"})]})]})]}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'waxell_observe.retry(\n attempt=2,\n reason="Rate limit exceeded",\n strategy="fallback",\n original_error="429 Too Many Requests",\n fallback_to="gpt-4o-mini",\n)\n'})}),"\n",(0,d.jsx)(n.h3,{id:"get_context",children:"get_context"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"import waxell_observe\n\nwaxell_observe.get_context() -> WaxellContext | None\n"})}),"\n",(0,d.jsxs)(n.p,{children:["Get the current ",(0,d.jsx)(n.code,{children:"WaxellContext"})," if one is active, otherwise ",(0,d.jsx)(n.code,{children:"None"}),"."]}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'ctx = waxell_observe.get_context()\nif ctx:\n ctx.record_llm_call(model="gpt-4o", tokens_in=100, tokens_out=50)\n'})}),"\n",(0,d.jsx)(n.h3,{id:"input",children:"input"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'import waxell_observe\n\nwaxell_observe.input(prompt: str = "", *, action: str = "input") -> str\n'})}),"\n",(0,d.jsxs)(n.p,{children:["Drop-in replacement for Python's built-in ",(0,d.jsx)(n.code,{children:"input()"}),". Calls ",(0,d.jsx)(n.code,{children:"input(prompt)"})," and records the prompt, response, and elapsed time as a ",(0,d.jsx)(n.code,{children:"human_turn"})," IO span."]}),"\n",(0,d.jsxs)(n.p,{children:["Falls back to plain ",(0,d.jsx)(n.code,{children:"input()"})," if called outside a ",(0,d.jsx)(n.code,{children:"WaxellContext"}),"."]}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'answer = waxell_observe.input("Approve? (y/n): ")\n'})}),"\n",(0,d.jsx)(n.h3,{id:"human_turn",children:"human_turn"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'import waxell_observe\n\nwaxell_observe.human_turn(\n prompt: str = "",\n channel: str = "terminal",\n action: str = "",\n metadata: dict | None = None,\n) -> HumanTurn | _NoOpHumanTurn\n'})}),"\n",(0,d.jsx)(n.p,{children:"Returns a context manager that captures a human interaction as a timed IO span. Use for non-terminal channels (Slack, webhooks, UI)."}),"\n",(0,d.jsxs)(n.p,{children:["Returns a no-op if called outside a ",(0,d.jsx)(n.code,{children:"WaxellContext"}),"."]}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'with waxell_observe.human_turn(prompt="Deploy?", channel="slack", action="approval") as turn:\n response = await wait_for_reaction()\n turn.set_response(response)\n'})}),"\n",(0,d.jsx)(n.h3,{id:"human_interaction",children:"human_interaction"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'import waxell_observe\n\nwaxell_observe.human_interaction(\n prompt: str = "",\n response: str = "",\n channel: str = "terminal",\n action: str = "",\n elapsed_seconds: float | None = None,\n metadata: dict | None = None,\n) -> None\n'})}),"\n",(0,d.jsxs)(n.p,{children:["Record a completed human interaction. One-shot alternative to ",(0,d.jsx)(n.code,{children:"human_turn()"})," when you already have all the data."]}),"\n",(0,d.jsxs)(n.p,{children:["No-op if called outside a ",(0,d.jsx)(n.code,{children:"WaxellContext"}),"."]}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'waxell_observe.human_interaction(\n prompt="Pick target",\n response="staging",\n channel="slack",\n elapsed_seconds=12.5,\n)\n'})}),"\n",(0,d.jsx)(n.h3,{id:"user_message",children:"user_message"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"import waxell_observe\n\nwaxell_observe.user_message(content: str, *, metadata: dict | None = None) -> None\n"})}
1),"\n",(0,d.jsx)(n.p,{children:"Record an inbound user message on the current context. Use in interactive agents (chat, REPL) to make user inputs visible in the trace alongside LLM calls and tool invocations."}),"\n",(0,d.jsxs)(n.p,{children:["No-op if called outside a ",(0,d.jsx)(n.code,{children:"WaxellContext"}),"."]}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'waxell_observe.user_message("What\'s the weather in Paris?")\n'})}),"\n",(0,d.jsx)(n.h3,{id:"agent_response",children:"agent_response"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"import waxell_observe\n\nwaxell_observe.agent_response(content: str, *, metadata: dict | None = None) -> None\n"})}),"\n",(0,d.jsx)(n.p,{children:"Record an outbound agent response on the current context. Use to trace what the agent communicated back to the user."}),"\n",(0,d.jsxs)(n.p,{children:["No-op if called outside a ",(0,d.jsx)(n.code,{children:"WaxellContext"}),"."]}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'waxell_observe.agent_response("It\'s currently 22\xb0C and sunny in Paris.")\n'})}),"\n",(0,d.jsx)(n.h3,{id:"communication",children:"communication"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'import waxell_observe\n\nwaxell_observe.communication(\n *,\n channel: str,\n recipient: str = "",\n body: str = "",\n subject: str = "",\n metadata: dict | None = None,\n) -> None\n'})}),"\n",(0,d.jsx)(n.p,{children:"Record an outbound communication on the current context. Use to track messages sent via external channels (Slack, email, SMS, webhooks) for communication governance policy evaluation."}),"\n",(0,d.jsxs)(n.p,{children:["No-op if called outside a ",(0,d.jsx)(n.code,{children:"WaxellContext"}),"."]}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'waxell_observe.communication(\n channel="slack",\n recipient="#ops-alerts",\n body="Deployment completed",\n subject="Deploy Notification",\n)\n'})}),"\n",(0,d.jsx)(n.h3,{id:"approval_request",children:"approval_request"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'import waxell_observe\n\nwaxell_observe.approval_request(\n action_type: str,\n approvers: list[str] | None = None,\n timeout_minutes: float | None = None,\n reason: str = "",\n metadata: dict | None = None,\n) -> None\n'})}),"\n",(0,d.jsxs)(n.p,{children:["Record an approval request on the current context. Call after catching ",(0,d.jsx)(n.code,{children:"PolicyViolationError"})," to record that an approval workflow was initiated."]}),"\n",(0,d.jsxs)(n.p,{children:["No-op if called outside a ",(0,d.jsx)(n.code,{children:"WaxellContext"}),"."]}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"action_type"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsx)(n.td,{children:"The action awaiting approval"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"approvers"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"list[str] | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Who can approve (emails, usernames)"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"timeout_minutes"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"float | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Approval window duration"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"reason"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"Why approval is needed"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"metadata"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"dict | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Additional context"})]})]})]}),"\n",(0,d.jsx)(n.h3,{id:"approval_response",children:"approval_response"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'import waxell_observe\n\nwaxell_observe.a
1pproval_response(\n action_type: str,\n decision: str,\n approver: str = "",\n elapsed_seconds: float | None = None,\n metadata: dict | None = None,\n) -> None\n'})}),"\n",(0,d.jsx)(n.p,{children:"Record an approval decision on the current context. Call after the human-in-the-loop decides or the approval window expires."}),"\n",(0,d.jsxs)(n.p,{children:["No-op if called outside a ",(0,d.jsx)(n.code,{children:"WaxellContext"}),"."]}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"action_type"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsx)(n.td,{children:"The action that was awaiting approval"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"decision"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsxs)(n.td,{children:[(0,d.jsx)(n.code,{children:'"approved"'}),", ",(0,d.jsx)(n.code,{children:'"denied"'}),", or ",(0,d.jsx)(n.code,{children:'"timeout"'})]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"approver"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"Who approved/denied"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"elapsed_seconds"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"float | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Time from block to decision"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"metadata"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"dict | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Additional context"})]})]})]}),"\n",(0,d.jsx)(n.h3,{id:"flush",children:"flush"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"import waxell_observe\n\nawait waxell_observe.flush() -> None\n"})}),"\n",(0,d.jsx)(n.p,{children:"Flush buffered data on the current context. Use in long-running contexts (REPLs, chat sessions) to make data visible in the UI before the context exits."}),"\n",(0,d.jsxs)(n.p,{children:["No-op if called outside a ",(0,d.jsx)(n.code,{children:"WaxellContext"}),"."]}),"\n",(0,d.jsx)(n.h3,{id:"flush_sync",children:"flush_sync"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"import waxell_observe\n\nwaxell_observe.flush_sync() -> None\n"})}),"\n",(0,d.jsxs)(n.p,{children:["Synchronous version of ",(0,d.jsx)(n.code,{children:"flush()"}),". Use in sync code."]}),"\n",(0,d.jsxs)(n.p,{children:["No-op if called outside a ",(0,d.jsx)(n.code,{children:"WaxellContext"}),"."]}),"\n",(0,d.jsx)(n.h3,{id:"diagnose",children:"diagnose"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"import waxell_observe\n\nwaxell_observe.diagnose() -> dict\n"})}),"\n",(0,d.jsx)(n.p,{children:"Introspect the SDK state. Returns a dict with:"}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Key"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"sdk_version"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsxs)(n.td,{children:["Package version (e.g. ",(0,d.jsx)(n.code,{children:'"0.0.40"'}),")"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"initialized"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"bool"})}),(0,d.jsxs)(n.td,{children:["Whether ",(0,d.jsx)(n.code,{children:"init()"})," was called"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"active_instrumentors"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"list[str]"})}),(0,d.jsx)(n.td,{children:"Names of active instrumentors"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"detected_libraries"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"dict[str, str]"})}),(0,d.jsx)(n.td,{children:"Installed library versions"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"config"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"dict"})}),(0,d.jsx)(n.td,{children:"Current API URL, key status"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"tracing"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"dict"})}),(0,d.jsx)(n.td,{children:"OTel availability and status"})]})]})]}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'import waxell_observe as waxell\nwaxell.init(
1)\n\ninfo = waxell.diagnose()\nprint(info["active_instrumentors"]) # ["openai", "anthropic", ...]\nprint(info["sdk_version"]) # "0.0.40"\n'})}),"\n",(0,d.jsx)(n.h3,{id:"prompt_approval",children:"prompt_approval"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"import waxell_observe\n\nwaxell_observe.prompt_approval(error: PolicyViolationError) -> ApprovalDecision\n"})}),"\n",(0,d.jsxs)(n.p,{children:["Built-in ",(0,d.jsx)(n.code,{children:"on_policy_block"})," handler. Prints a terminal banner with the block reason, approvers, and timeout, then prompts ",(0,d.jsx)(n.code,{children:"y/n"}),"."]}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'@waxell_observe.observe(\n agent_name="my-agent",\n enforce_policy=True,\n on_policy_block=waxell_observe.prompt_approval,\n)\nasync def my_function():\n ...\n'})}),"\n",(0,d.jsx)(n.h3,{id:"auto_approve--auto_deny",children:"auto_approve / auto_deny"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"import waxell_observe\n\nwaxell_observe.auto_approve(error: PolicyViolationError) -> ApprovalDecision\nwaxell_observe.auto_deny(error: PolicyViolationError) -> ApprovalDecision\n"})}),"\n",(0,d.jsxs)(n.p,{children:["Test helpers. ",(0,d.jsx)(n.code,{children:"auto_approve"})," always returns ",(0,d.jsx)(n.code,{children:"ApprovalDecision(approved=True)"}),". ",(0,d.jsx)(n.code,{children:"auto_deny"})," always returns ",(0,d.jsx)(n.code,{children:"ApprovalDecision(approved=False)"}),"."]}),"\n",(0,d.jsx)(n.hr,{}),"\n",(0,d.jsx)(n.h2,{id:"drop-in-imports",children:"Drop-in Imports"}),"\n",(0,d.jsxs)(n.p,{children:["Pre-instrumented modules that you can import directly, no ",(0,d.jsx)(n.code,{children:"init()"})," required:"]}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"from waxell_observe.openai import openai\nfrom waxell_observe.anthropic import anthropic\n"})}),"\n",(0,d.jsx)(n.p,{children:"These modules are thin wrappers around the real SDKs with auto-instrumentation already applied. All OpenAI/Anthropic calls made through these imports are automatically traced."}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'from waxell_observe.openai import openai\n\nclient = openai.OpenAI()\nresponse = client.chat.completions.create(\n model="gpt-4o",\n messages=[{"role": "user", "content": "Hello!"}]\n)\n# Automatically traced with model, tokens, cost, latency\n'})}),"\n",(0,d.jsx)(n.hr,{}),"\n",(0,d.jsx)(n.h2,{id:"instrumentation-functions",children:"Instrumentation Functions"}),"\n",(0,d.jsx)(n.h3,{id:"instrument_all",children:"instrument_all"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"from waxell_observe.instrumentors import instrument_all\n\ninstrument_all(libraries: list[str] | None = None) -> dict[str, bool]\n"})}),"\n",(0,d.jsxs)(n.p,{children:["Manually instrument LLM libraries. Called automatically by ",(0,d.jsx)(n.code,{children:"init()"}),", but can be called directly if needed."]}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsx)(n.tbody,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"libraries"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"list[str] | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsxs)(n.td,{children:["Libraries to instrument. ",(0,d.jsx)(n.code,{children:"None"})," means auto-detect all installed"]})]})})]}),"\n",(0,d.jsxs)(n.p,{children:[(0,d.jsx)(n.strong,{children:"Returns:"})," A dict mapping library name to whether instrumentation succeeded (e.g. ",(0,d.jsx)(n.code,{children:'{"openai": True, "anthropic": True}'}),")."]}),"\n",(0,d.jsxs)(n.p,{children:[(0,d.jsx)(n.strong,{children:"Supported libraries:"})," 200+ LLM providers, vector databases, embedding models, frameworks, and more. Core providers include ",(0,d.jsx)(n.code,{children:"open
1ai"}),", ",(0,d.jsx)(n.code,{children:"anthropic"}),", ",(0,d.jsx)(n.code,{children:"litellm"}),", ",(0,d.jsx)(n.code,{children:"groq"}),", ",(0,d.jsx)(n.code,{children:"huggingface"}),", ",(0,d.jsx)(n.code,{children:"gemini"}),", ",(0,d.jsx)(n.code,{children:"cohere"}),", ",(0,d.jsx)(n.code,{children:"mistral"}),", ",(0,d.jsx)(n.code,{children:"together"}),", ",(0,d.jsx)(n.code,{children:"ai21"}),", ",(0,d.jsx)(n.code,{children:"bedrock"}),", ",(0,d.jsx)(n.code,{children:"vertex_ai"}),". See ",(0,d.jsx)(n.a,{href:"../integrations/auto-instrumentation",children:"Auto-Instrumentation"})," for the full list."]}),"\n",(0,d.jsx)(n.h3,{id:"uninstrument_all",children:"uninstrument_all"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"from waxell_observe.instrumentors import uninstrument_all\n\nuninstrument_all() -> None\n"})}),"\n",(0,d.jsxs)(n.p,{children:["Remove all instrumentation patches. Called automatically by ",(0,d.jsx)(n.code,{children:"shutdown()"}),"."]}),"\n",(0,d.jsx)(n.hr,{}),"\n",(0,d.jsx)(n.h2,{id:"opentelemetry-functions",children:"OpenTelemetry Functions"}),"\n",(0,d.jsxs)(n.p,{children:["These functions manage the OTel tracing layer. They are called automatically by ",(0,d.jsx)(n.code,{children:"init()"})," and ",(0,d.jsx)(n.code,{children:"shutdown()"}),", but can be used directly for advanced control."]}),"\n",(0,d.jsx)(n.h3,{id:"init_tracing",children:"init_tracing"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"from waxell_observe.tracing import init_tracing\n\ninit_tracing(\n api_url: str | None = None,\n api_key: str | None = None,\n otel_endpoint: str | None = None,\n tenant_id: str | None = None,\n debug: bool | None = None,\n capture_content: bool = False,\n shutdown_on_exit: bool = True,\n resource_attributes: dict | None = None,\n) -> None\n"})}),"\n",(0,d.jsx)(n.p,{children:"Initialize OpenTelemetry tracing with OTLP HTTP export to the Waxell backend."}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"api_url"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Waxell API URL. Resolved from config if not provided"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"api_key"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Waxell API key. Resolved from config if not provided"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"otel_endpoint"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Explicit OTel collector endpoint. Auto-discovered if not provided"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"tenant_id"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Explicit tenant ID for trace routing. Auto-discovered from API key if not provided"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"debug"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"bool | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsxs)(n.td,{children:["Enable debug logging and console span export. Defaults to ",(0,d.jsx)(n.code,{children:"WAXELL_DEBUG"})," env var"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"capture_content"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"bool"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"False"})}),(0,d.jsx)(n.td,{children:"Include prompt/response content in spans"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"shutdown_on_exit"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"bool"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"True"})}),(0,d.jsx)(n.td,{children:"Register atexit handler for clean shutdown"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"resource_attributes"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"dict | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Extra OTel resource attributes"})]})]})]}),"\n",(0,d.jsx)(n.h3,{id:"flush_tracing",children:"flush_tracing"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"from waxell_observe.tracing import flush_tracing\n\nflush_tracing(timeout_millis: int = 30000) -> None\n"})}),"\n",(0,d.jsx)(n.p,{children:"Force flush pending spans to the backend."}),"\n",(0,d.jsx)(n.h3,{id:"shutdown_tracing",children:"shutdown_tracing"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"from waxell_observe.tracing import shutdown_tracing\n\nshutdown_tracing() -> None\n"})}),"\n",(0,d.jsx)(n.p,{children:"Shut down the TracerProvider and flush remaining spans."}),"\n",(0,d.jsx)(n.hr,{}),"\n",(0,d.jsx)(n.h2,{id:"waxellobserveclient",children:"WaxellOb
1serveClient"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"from waxell_observe import WaxellObserveClient\n"})}),"\n",(0,d.jsx)(n.p,{children:"HTTP client for the Waxell Observe API. Handles configuration resolution, authentication, and all API interactions."}),"\n",(0,d.jsx)(n.h3,{id:"constructor",children:"Constructor"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"WaxellObserveClient(\n api_url: str | None = None,\n api_key: str | None = None,\n)\n"})}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"api_url"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Control plane URL. Overrides all other config sources"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"api_key"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"API key. Overrides all other config sources"})]})]})]}),"\n",(0,d.jsx)(n.h3,{id:"class-methods",children:"Class Methods"}),"\n",(0,d.jsx)(n.h4,{id:"configure",children:"configure"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"@classmethod\nWaxellObserveClient.configure(api_url: str, api_key: str) -> None\n"})}),"\n",(0,d.jsxs)(n.p,{children:["Set global configuration for all instances. Call once at application startup. All subsequent ",(0,d.jsx)(n.code,{children:"WaxellObserveClient()"})," instances will use these values (unless overridden by constructor arguments)."]}),"\n",(0,d.jsx)(n.h4,{id:"get_config",children:"get_config"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"@classmethod\nWaxellObserveClient.get_config() -> ObserveConfig | None\n"})}),"\n",(0,d.jsxs)(n.p,{children:["Returns the current global configuration, or ",(0,d.jsx)(n.code,{children:"None"})," if ",(0,d.jsx)(n.code,{children:"configure()"})," has not been called."]}),"\n",(0,d.jsx)(n.h4,{id:"is_configured",children:"is_configured"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"@classmethod\nWaxellObserveClient.is_configured() -> bool\n"})}),"\n",(0,d.jsxs)(n.p,{children:["Returns ",(0,d.jsx)(n.code,{children:"True"})," if global configuration is set and both ",(0,d.jsx)(n.code,{children:"api_url"})," and ",(0,d.jsx)(n.code,{children:"api_key"})," are non-empty."]}),"\n",(0,d.jsx)(n.h3,{id:"async-methods",children:"Async Methods"}),"\n",(0,d.jsx)(n.h4,{id:"start_run",children:"start_run"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'async start_run(\n agent_name: str,\n workflow_name: str = "default",\n inputs: dict | None = None,\n metadata: dict | None = None,\n trace_id: str = "",\n user_id: str = "",\n user_group: str = "",\n session_id: str = "",\n parent_workflow_id: str = "",\n root_workflow_id: str = "",\n) -> RunInfo\n'})}),"\n",(0,d.jsx)(n.p,{children:"Start an execution run on the control plane."}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"agent_name"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsx)(n.td,{children:"Agent name"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"workflow_name"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'"default"'})}),(0,d.jsx)(n.td,{children:"Workflow name"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"inputs"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"dict | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Input data for the run"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"metadata"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"dict | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Arbitrary metadata"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"trace_id"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}
1),(0,d.jsx)(n.td,{children:"External trace ID for correlation"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"user_id"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"User identifier for per-user analytics"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"user_group"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"User group for authorization policies"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"session_id"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"Session ID for grouping related runs"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"parent_workflow_id"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"Parent workflow ID for nested agent lineage"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"root_workflow_id"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"Root workflow ID for top-level lineage tracking"})]})]})]}),"\n",(0,d.jsxs)(n.p,{children:[(0,d.jsx)(n.strong,{children:"Returns:"})," ",(0,d.jsx)(n.code,{children:"RunInfo"})," with ",(0,d.jsx)(n.code,{children:"run_id"}),", ",(0,d.jsx)(n.code,{children:"workflow_id"}),", and ",(0,d.jsx)(n.code,{children:"started_at"}),"."]}),"\n",(0,d.jsx)(n.h4,{id:"complete_run",children:"complete_run"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'async complete_run(\n run_id: str,\n result: dict | None = None,\n status: str = "success",\n error: str = "",\n error_type: str = "",\n traceback: str = "",\n steps: list | None = None,\n trace_id: str = "",\n root_span_id: str = "",\n) -> RunCompleteResult\n'})}),"\n",(0,d.jsx)(n.p,{children:"Complete an execution run. Returns governance info including retry feedback."}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"run_id"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsxs)(n.td,{children:["Run ID from ",(0,d.jsx)(n.code,{children:"start_run"})]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"result"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"dict | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Result data"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"status"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'"success"'})}),(0,d.jsxs)(n.td,{children:[(0,d.jsx)(n.code,{children:'"success"'})," or ",(0,d.jsx)(n.code,{children:'"error"'})]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"error"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"Error message"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"error_type"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsxs)(n.td,{children:["Exception class name (e.g. ",(0,d.jsx)(n.code,{children:'"ValueError"'}),")"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"traceback"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"Full traceback string"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"steps"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"list | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Additional steps"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"trace_id"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"OTel trace ID for correlation"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"root_span_id"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"OTel root span ID for correlation"})]})]})]}),"\n",(0,d.jsxs)(n.p,{children:[(0,d.jsx)(n.strong,{children:"Returns:"})," ",(0,d.jsx)(n.code,{children:"RunCompleteResult"})," with ",(0,d.jsx)(n.code,{children:"run_id"}),", ",(0,d.jsx)(n.code,{children:"duration"}),", ",(0,d.jsx)(n.code,{children:"governance_action"}),", ",(0,d.jsx)(n.code,{children:"governance_reason"}),", ",(0,d.jsx)(n.code,{children:"retry_feedback"}),", and ",(0,d.jsx)(n.code,{children:"max_retries"}),"."]}),"\n",(0,d.jsx)(n.h4,{id:"record_llm_calls",children:"record_llm_calls"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"async record_llm_calls(\n run_id: str,\n calls: list[dict],\n) -> dict\n"})}),"\n",(0,d.jsxs)(n.p,{children:["Record one or more LLM calls for a run. No-op if ",(0,d.jsx)(n.code,{children:"calls"})," is empty."]}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"run_id"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"Run ID"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"calls"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"list[dict]"})}),(0,d.jsxs)(n.td,{children:["List of LLM call dicts with keys: ",(0,d.jsx)(n.code,{children:"model"}),", ",(0,d.jsx)(n.code,{children:"tokens_in"}),", ",(0,d.jsx)(n.code,{children:"tokens_out"}),", and optionally ",(0,d.jsx)(n.code,{children:"cost"}),", ",(0,d.jsx)(n.code,{children:"task"}),", ",(0,d.jsx)(n.code,{children:"prompt_preview"}),", ",(0,d.jsx)(n.code,{children:"response_preview"})]})]})]})]}),"\n",(0,d.jsxs)(n.p,{children:[(0,d.jsx)(n.strong,{children:"Returns:"})," Server response dict (includes ",(0,d.jsx)(n.code,{children:"governance"})," field for mid-execution governance)."]}),"\n",(0,d.jsx)(n.h4,{id:"record_steps",children:"record_steps"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"async record_steps(\n run_id: str,\n steps: list[dict],\n) -> dict\n"})}),"\n",(0,d.jsxs)(n.p,{children:["Record execution steps for a run. No-op if ",(0,d.jsx)(n.code,{children:"steps"})," is empty."]}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"run_id"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"Run ID"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"steps"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"list[dict]"})}),(0,d.jsxs)(n.td,{children:["List of step dicts with keys: ",(0,d.jsx)(n.code,{children:"step_
1name"})," and optionally ",(0,d.jsx)(n.code,{children:"output"}),", ",(0,d.jsx)(n.code,{children:"position"})]})]})]})]}),"\n",(0,d.jsxs)(n.p,{children:[(0,d.jsx)(n.strong,{children:"Returns:"})," Server response dict (includes ",(0,d.jsx)(n.code,{children:"governance"})," field for mid-execution governance)."]}),"\n",(0,d.jsx)(n.h4,{id:"record_scores",children:"record_scores"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"async record_scores(\n run_id: str,\n scores: list[dict],\n) -> dict\n"})}),"\n",(0,d.jsx)(n.p,{children:"Record scores (user feedback, evaluation results) for a run."}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"run_id"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"Run ID"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"scores"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"list[dict]"})}),(0,d.jsxs)(n.td,{children:["List of score dicts. Each dict should contain: ",(0,d.jsx)(n.code,{children:"name"}),", ",(0,d.jsx)(n.code,{children:"data_type"})," (",(0,d.jsx)(n.code,{children:'"numeric"'}),", ",(0,d.jsx)(n.code,{children:'"categorical"'}),", or ",(0,d.jsx)(n.code,{children:'"boolean"'}),"), and either ",(0,d.jsx)(n.code,{children:"numeric_value"})," or ",(0,d.jsx)(n.code,{children:"string_value"})," depending on data type. Optional: ",(0,d.jsx)(n.code,{children:"comment"})]})]})]})]}),"\n",(0,d.jsxs)(n.p,{children:["No-op if ",(0,d.jsx)(n.code,{children:"scores"})," is empty. ",(0,d.jsx)(n.strong,{children:"Returns:"})," Server response dict."]}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'await client.record_scores(run_id, scores=[\n {"name": "accuracy", "data_type": "numeric", "numeric_value": 0.95},\n {"name": "thumbs_up", "data_type": "boolean", "numeric_value": 1.0, "string_value": "true"}
1,\n {"name": "category", "data_type": "categorical", "string_value": "helpful", "comment": "User feedback"},\n])\n'})}),"\n",(0,d.jsx)(n.h4,{id:"get_prompt",children:"get_prompt"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'async get_prompt(\n name: str,\n *,\n label: str = "",\n version: int = 0,\n) -> PromptInfo\n'})}),"\n",(0,d.jsxs)(n.p,{children:["Fetch a prompt from the control plane. Returns the prompt content, config, and a ",(0,d.jsx)(n.code,{children:"compile()"})," helper for template rendering."]}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"name"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsx)(n.td,{children:"Prompt name"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"label"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsxs)(n.td,{children:["Label to fetch (e.g. ",(0,d.jsx)(n.code,{children:'"production"'}),"). If empty, fetches latest version"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"version"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"int"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"0"})}),(0,d.jsxs)(n.td,{children:["Specific version number. Takes precedence over ",(0,d.jsx)(n.code,{children:"label"})," if both provided"]})]})]})]}),"\n",(0,d.jsxs)(n.p,{children:[(0,d.jsx)(n.strong,{children:"Returns:"})," ",(0,d.jsx)(n.code,{children:"PromptInfo"})," with ",(0,d.jsx)(n.code,{children:"name"}),", ",(0,d.jsx)(n.code,{children:"version"}),", ",(0,d.jsx)(n.code,{children:"prompt_type"}),", ",(0,d.jsx)(n.code,{children:"content"}),", ",(0,d.jsx)(n.code,{children:"config"}),", ",(0,d.jsx)(n.code,{children:"labels"}),", and ",(0,d.jsx)(n.code,{children:"compile()"})," method."]}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'# Fetch by label (recommended for production)\nprompt = await client.get_prompt("summarizer", label="production")\nrendered = prompt.compile(topic="AI safety", length="short")\n\n# Fetch specific version\nprompt = await client.get_prompt("summarizer", version=3)\n\n# Fetch latest\nprompt = await client.get_prompt("summarizer")\n'})}),"\n",(0,d.jsx)(n.h4,{id:"check_policy",children:"check_policy"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'async check_policy(\n agent_name: str,\n workflow_name: str = "",\n agent_id: str = "",\n) -> PolicyCheckResult\n'})}),"\n",(0,d.jsx)(n.p,{children:"Check if execution is allowed by policies."}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"agent_name"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsx)(n.td,{children:"Agent name"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"workflow_name"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"Workflow name for scoped policies"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"agent_id"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"Specific agent instance ID"})]})]})]}),"\n",(0,d.jsxs)(n.p,{children:[(0,d.jsx)(n.strong,{children:"Returns:"})," ",(0,d.jsx)(n.code,{children:"PolicyCheckResult"}),"."]}),"\n",(0,d.jsx)(n.h4,{id:"record_events",children:"record_events"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"async record_events(events: list[dict]) -> None\n"})}),"\n",(0,d.jsxs)(n.p,{children:["Record governance events. No-op if ",(0,d.jsx)(n.code,{children:"events"})," is empty."]}),"\n",(0,d.jsx)(n.h4,{id:"close",children:"close"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"async close() -> None\n"})}),"\n",(0,d.jsx)(n.p,{children:"Close the underlying HTTP client. Call this when you are done using the client."}),"\n",(0,d.jsx)(n.h3,{id:"sync-methods",children:"Sync Methods"}),"\n",(0,d.jsxs)(n.p,{children:["Each async method has a synchronous counterpart that uses ",(0,d.jsx)(n.code,{children:"asyncio.run()"})," internally:"]}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Async Method"}),(0,d.jsx)(n.th,{children:"Sync Method"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"start_run()"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"start_run_sync()"})})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"complete_run()"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"complete_run_sync()"})})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"record_llm_calls()"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"record_llm_calls_sync()"})})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"record_steps()"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"record_steps_sync()"})})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"record_scores()"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"record_scores_sync()"})})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"record_spans()"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"record_spans_sync()"})})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"check_policy()"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"check_policy_sync()"})})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"record_events()"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"record_events_sync()"})})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"get_prompt()"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"get_prompt_sync()"})})]})]})]}),"\n",(0,d.jsx)(n.p,{children:"Sync methods accept the same keyword arguments as their async counterparts."}),"\n",(0,d.jsx)(n.admonition,{type:"warning",children:(0,d.jsx)(n.p,{children:"Sync methods cannot be used inside an already-running async event loop. If a running event loop is detected, the SDK delegates to a background thread with a 60-second timeout. Use the async versions in async code when possible."})}),"\n",(0,d.jsx)(n.hr,{}),"\n",(0,d.jsx)(n.h2,{id:"waxellcontext",children:"WaxellContext"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"from waxell_observe import WaxellContext\n"})}),"\n",(0,d.jsx)(n.p,{children:"Context manager (sync and async) that wraps agent execution with observability and governance."}),"\n",(0,d.jsx)(n.h3,{id:"constructor-1",children:"Constructor"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'WaxellContext(\n agent_name: str,\n workflow_name: str = "default",\n inputs: dict | None = None,\n metadata: dict | None = None,\n client: WaxellOb
1serveClient | None = None,\n enforce_policy: bool = True,\n session_id: str = "",\n user_id: str = "",\n user_group: str = "",\n mid_execution_governance: bool = False,\n auto_grounding: bool = False,\n on_policy_block: Callable | None = None,\n)\n'})}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"agent_name"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsx)(n.td,{children:"Agent name"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"workflow_name"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'"default"'})}),(0,d.jsx)(n.td,{children:"Workflow name"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"inputs"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"dict | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Input data for the run"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"metadata"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"dict | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Arbitrary metadata"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"client"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"WaxellObserveClient | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsxs)(n.td,{children:["Pre-configured client. If ",(0,d.jsx)(n.code,{children:"None"}),", creates one using global config"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"enforce_policy"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"bool"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"True"})}),(0,d.jsx)(n.td,{children:"Check policies on entry"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"session_id"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsxs)(n.td,{children:["Session ID for grouping related runs. Use ",(0,d.jsx)(n.code,{children:"generate_session_id()"})," to create one"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"user_id"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"User identifier for per-user analytics and tracking"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"user_group"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsxs)(n.td,{children:["User group for authorization policies (e.g., ",(0,d.jsx)(n.code,{children:'"enterprise"'}),", ",(0,d.jsx)(n.code,{children:'"free"'}),")"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"mid_execution_governance"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"bool"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"False"})}),(0,d.jsxs)(n.td,{children:["Enable cooperative mid-execution governance. When ",(0,d.jsx)(n.code,{children:"True"}),", each ",(0,d.jsx)(n.code,{children:"record_step()"})," flushes data and checks for policy violations"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"auto_grounding"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"bool"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"False"})}),(0,d.jsx)(n.td,{children:"Auto-bridge retrieval scores to grounding governance"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"on_policy_block"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"Callable | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsxs)(n.td,{children:["Callback for policy blocks. Receives ",(0,d.jsx)(n.code,{children:"PolicyViolationError"}),", returns ",(0,d.jsx)(n.code,{children:"ApprovalDecision"})]})]})]})]}),"\n",(0,d.jsx)(n.h3,{id:"usage",children:"Usage"}),"\n",(0,d.jsxs)(n.p,{children:["Works as both ",(0,d.jsx)(n.code,{children:"async with"})," (async code) and plain ",(0,d.jsx)(n.code,{children:"with"})," (sync code):"]}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'# Async\nasync with Waxell
1Context(agent_name="my-agent") as ctx:\n result = await my_agent.run(query)\n ctx.set_result({"output": result})\n\n# Sync\nwith WaxellContext(agent_name="my-agent") as ctx:\n result = my_agent.run(query)\n ctx.set_result({"output": result})\n'})}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"With session and user tracking:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'from waxell_observe import WaxellContext, generate_session_id\n\nsession = generate_session_id()\n\nasync with WaxellContext(\n agent_name="my-agent",\n session_id=session,\n user_id="user_456",\n) as ctx:\n ctx.set_tag("environment", "production")\n ctx.set_metadata("request_id", "req_abc123")\n result = await my_agent.run(query)\n ctx.record_score("relevance", 0.92)\n ctx.set_result({"output": result})\n'})}),"\n",(0,d.jsx)(n.h3,{id:"lifecycle",children:"Lifecycle"}),"\n",(0,d.jsxs)(n.p,{children:["On enter (",(0,d.jsx)(n.code,{children:"__aenter__"})," / ",(0,d.jsx)(n.code,{children:"__enter__"}),"):"]}),"\n",(0,d.jsxs)(n.ol,{children:["\n",(0,d.jsxs)(n.li,{children:["Checks policies (if ",(0,d.jsx)(n.code,{children:"enforce_policy=True"}),"). Raises ",(0,d.jsx)(n.code,{children:"PolicyViolationError"})," if blocked."]}),"\n",(0,d.jsxs)(n.li,{children:["Starts an execution run on the control plane. ",(0,d.jsx)(n.code,{children:"session_id"})," and ",(0,d.jsx)(n.code,{children:"user_id"})," are injected into the run metadata."]}),"\n",(0,d.jsx)(n.li,{children:"Creates an OTel agent span (if tracing is initialized). Session and user IDs are set as span attributes."}),"\n",(0,d.jsx)(n.li,{children:"Sets the ContextVar so auto-instrumented LLM calls are associated with this run."}),"\n"]}),"\n",(0,d.jsxs)(n.p,{children:["On exit (",(0,d.jsx)(n.code,{children:"__aexit__"})," / ",(0,d.jsx)(n.code,{children:"__exit__"}),"):"]}),"\n",(0,d.jsxs)(n.ol,{children:["\n",(0,d.jsxs)(n.li,{children:["Flushes buffered LLM calls via ",(0,d.jsx)(n.code,{children:"record_llm_calls"}),"."]}),"\n",(0,d.jsxs)(n.li,{children:["Flushes buffered steps via ",(0,d.jsx)(n.code,{children:"record_steps"}),"."]}),"\n",(0,d.jsxs)(n.li,{children:["Flushes buffered scores via ",(0,d.jsx)(n.code,{children:"record_scores"}),"."]}),"\n",(0,d.jsxs)(n.li,{children:["Flushes buffered behavior spans via ",(0,d.jsx)(n.code,{children:"record_spans"}),"."]}),"\n",(0,d.jsx)(n.li,{children:"Completes the run with result or error status."}),"\n",(0,d.jsx)(n.li,{children:"Ends the OTel agent span and clears the ContextVar."}),"\n"]}),"\n",(0,d.jsxs)(n.p,{children:["The sync path (",(0,d.jsx)(n.code,{children:"__enter__"})," / ",(0,d.jsx)(n.code,{children:"__exit__"}),") uses synchronous HTTP calls and sets the ContextVar in the calling thread, ensuring auto-instrumentation works correctly."]}),"\n",(0,d.jsx)(n.h3,{id:"methods",children:"Methods"}),"\n",(0,d.jsx)(n.h4,{id:"record_llm_call",children:"record_llm_call"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'record_llm_call(\n *,\n model: str,\n tokens_in: int,\n tokens_out: int,\n cost: float = 0.0,\n task: str = "",\n prompt_preview: str = "",\n response_preview: str = "",\n duration_ms: int | None = None,\n provider: str = "",\n) -> None\n'})}),"\n",(0,d.jsxs)(n.p,{children:["Buffer an LLM call for later flushing. All parameters are keyword-only. If ",(0,d.jsx)(n.code,{children:"cost"})," is ",(0,d.jsx)(n.code,{children:"0.0"}),", it is automatically estimated using built-in model pricing. Also emits an OTel LLM span (if tracing is initialized)."]}),"\n",(0,d.jsx)(n.h4,{id:"record_step",children:"record_step"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"record_step(step_name: str, output: dict | None = None) -> None\n"})}),"\n",(0,d.jsxs)(n.p,{children:["Buffer an execution step. Steps are automatically numbered in the order they are recorded (via an internal ",(0,d.jsx)(n.code,{children:"position"})," counter). Also emits an OTel step span."]}),"\n",(0,d.jsxs)(n.p,{children:["If ",(0,d.jsx)(n.code,{children:"mid_execution_governance"})," is enabled, this method also flushes buffered data to the server and checks the governance response. Raises ",(0,d.jsx)(n.code,{children:"PolicyViolationError"})," if the server returns a block action."]}),"\n",(0,d.jsx)(n.h4,{id:"set_result",children:"set_result"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"set_result(result: dict) -> None\n"})}),"\n",(0,d.jsx)(n.p,{children:"Set the result to include when the run is completed."}),"\n",(0,d.jsx)(n.h4,{id:"record_score",children:"record_score"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'record_score(\n name: str,\n value: float | str | bool,\n data_type: str = "numeric",\n comment: str = "",\n) -> None\n'})}),"\n",(0,d.jsx)(n.p,{children:"Buffer a score (user feedback or evaluation result) for the current run. Scores are flushed to the server when the context exits."}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"name"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsxs)(n.td,{children:["Score name (e.g. ",(0,d.jsx)(n.code,{children:'"thumbs_up"'}),", ",(0,d.jsx)(n.code,{children:'"accuracy"'}),", ",(0,d.jsx)(n.code,{children:'"relevance"'}),")"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"value"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"float | str | bool"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsxs)(n.td,{children:["Score value. Type depends on ",(0,d.jsx)(n.code,{children:"data_type"})]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"data_type"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'"numeric"'})}),(0,d.jsxs)(n.td,{children:["One of ",(0,d.jsx)(n.code,{children:'"numeric"'}),", ",(0,d.jsx)(n.code,{children:'"categorical"'}),", or ",(0,d.jsx)(n.code,{children:'"boolean"'})]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"comment"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"Optional free-text comment"})]})]})]}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Value handling by data type:"})}),"\n",(0,d.jsxs)(n.ul,{children:["\n",(0,d.jsxs)(n.li,{children:[(0,d.jsx)(n.code,{children:'"numeric"'}),": ",(0,d.jsx)(n.code,{children:"value"})," is stored as ",(0,d.jsx)(n.code,{children:"numeric_value"})," (converted to float)"]}),"\n",(0,d.jsxs)(n.li,{children:[(0,d.jsx)(n.code,{children:'"boolean"'}),": ",(0,d.jsx)(n.code,{children:"value"})," is stored as both ",(0,d.jsx)(n.code,{children:"numeric_value"})," (",(0,d.jsx)(n.code,{children:"1.0"})," for truthy, ",(0,d.jsx)(n.code,{children:"0.0"})," for falsy) and ",(0,d.jsx)(n.code,{children:"string_value"})," (",(0,d.jsx)(n.code,{children:'"true"'})," or ",(0,d.jsx)(n.code,{children:'"false"'}),")"]}),"\n",(0,d.jsxs)(n.li,{children:[(0,d.jsx)(n.code,{children:'"categorical"'}),": ",(0,d.jsx)(n.code,{children:"value"})," is stored as ",(0,d.jsx)(n.code,{children:"string_value"})," (converted to string)"]}),"\n"]}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'async with Waxell
1Context(agent_name="my-agent") as ctx:\n result = await run_agent(query)\n ctx.record_score("accuracy", 0.95)\n ctx.record_score("thumbs_up", True, data_type="boolean")\n ctx.record_score("category", "helpful", data_type="categorical", comment="User selected")\n ctx.set_result({"output": result})\n'})}),"\n",(0,d.jsx)(n.h4,{id:"set_tag",children:"set_tag"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"set_tag(key: str, value: str) -> None\n"})}),"\n",(0,d.jsxs)(n.p,{children:["Set a searchable tag on the current agent span. Tags are string key-value pairs that become OTel span attributes with the ",(0,d.jsx)(n.code,{children:"waxell.tag."})," prefix."]}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"key"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"Tag name (alphanumeric, underscores, hyphens)"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"value"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"Tag value (string)"})]})]})]}),"\n",(0,d.jsx)(n.p,{children:"Tags are queryable in Grafana TraceQL:"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{children:'{ span.waxell.tag.environment = "production" }\n'})}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'async with WaxellContext(agent_name="my-agent") as ctx:\n ctx.set_tag("environment", "production")\n ctx.set_tag("customer_tier", "enterprise")\n ctx.set_tag("region", "us-east-1")\n'})}),"\n",(0,d.jsx)(n.h4,{id:"set_metadata",children:"set_metadata"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"set_metadata(key: str, value: Any) -> None\n"})}),"\n",(0,d.jsx)(n.p,{children:"Set metadata on the current agent span. Unlike tags, metadata values can be any JSON-serializable type. Complex values are automatically JSON-serialized for OTel compatibility."}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"key"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"Metadata key"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"value"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"Any"})}),(0,d.jsx)(n.td,{children:"Any JSON-serializable value"})]})]})]}),"\n",(0,d.jsx)(n.p,{children:"Metadata is queryable in Grafana TraceQL:"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{children:"{ span.waxell.meta.request_id != nil }\n"})}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'async with WaxellContext(agent_name="my-agent") as ctx:\n ctx.set_metadata("request_id", "req_abc123")\n ctx.set_metadata("config", {"temperature": 0.7, "max_tokens": 1000})\n ctx.set_metadata("retry_count", 2)\n'})}),"\n",(0,d.jsx)(n.h4,{id:"behavior-tracking-methods",children:"Behavior Tracking Methods"}),"\n",(0,d.jsxs)(n.p,{children:["These methods buffer behavior data as spans, flushed to the server on context exit via the ",(0,d.jsx)(n.code,{children:"POST /runs/{run_id}/spans/"})," endpoint."]}),"\n",(0,d.jsx)(n.h4,{id:"record_tool_call",children:"record_tool_call"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'record_tool_call(\n *,\n name: str,\n input: dict | str = "",\n output: dict | str = "",\n duration_ms: int | None = None,\n status: str = "ok",\n tool_type: str = "function",\n error: str = "",\n) -> None\n'})}),"\n",(0,d.jsx)(n.p,{children:"Buffer a tool/function call event."}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"name"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsxs)(n.td,{children:["Tool name (e.g. ",(0,d.jsx)(n.code,{children:'"web_search"'}),", ",(0,d.jsx)(n.code,{children:'"database_query"'}),")"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"input"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"dict | str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"Tool input parameters"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"output"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"dict | str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"Tool output/result"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"duration_ms"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"int | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Execution time in milliseconds"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"status"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'"ok"'})}),(0,d.jsxs)(n.td,{children:[(0,d.jsx)(n.code,{children:'"ok"'})," or ",(0,d.jsx)(n.code,{children:'"error"'})]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"tool_type"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'"function"'})}),(0,d.jsxs)(n.td,{children:[(0,d.jsx)(n.code,{children:'"function"'}),", ",(0,d.jsx)(n.code,{children:'"api"'}),", ",(0,d.jsx)(n.code,{children:'"database"'}),", or ",(0,d.jsx)(n.code,{children:'"retriever"'})]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"error"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsxs)(n.td,{children:["Error message if status is ",(0,d.jsx)(n.code,{children:'"error"'})]})]})]})]}),"\n",(0,d.jsx)(n.h4,{id:"record_retrieval",children:"record_retrieval"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'record_retrieval(\n *,\n query: str,\n documents: list[dict],\n source: str = "",\n duration_ms: int | None = None,\n top_k: int | None = None,\n scores: list[float] | None = None,\n) -> None\n'})}),"\n",(0,d.jsx)(n.p,{children:"Buffer a RAG retrieval operation."}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"query"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsx)(n.td,{children:"The retrieval query string"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"documents"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"list[dict]"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsxs)(n.td,{children:["Retrieved docs (e.g. ",(0,d.jsx)(n.code,{children:"[{id, title, score, snippet}]"}),")"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"source"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsxs)(n.td,{children:["Data source name (e.g. ",(0,d.jsx)(n.code,{children:'"pinecone"'}),", ",(0,d.jsx)(n.code,{children:'"elasticsearch"'}),")"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"duration_ms"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"int | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Retrieval time in milliseconds"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"top_k"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"int | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Number of documents requested"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"scores"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"list[float] | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Relevance scores for each retrieved document"})]})]})]}),"\n",(0,d.jsx)(n.h4,{id:"record_decision",children:"record_decision"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'record_decision(\n *,\n name: str,\n options: list[str],\n chosen: str,\n reasoning: str = "",\n confidence: float | None = None,\n metadata: dict | None = None,\n) -> None\n'})}),"\n",(0,d.jsx)(n.p,{children:"Buffer a decision/routing point."}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"name"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsxs)(n.td,{children:["Decision name (e.g. ",(0,d.jsx)(n.code,{children:'"route_to_agent"'}),", ",(0,d.jsx)(n.code,{children:'"select_model"'}),")"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"options"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"list[str]"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsx)(n.td,{children:"Available choices"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"chosen"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsx)(n.td,{children:"The selected option"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"reasoning"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"Why this option was chosen"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"confidence"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"float | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Confidence score (0.0-1.0)"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"metadata"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"dict | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Additional context"})]})]})]}),"\n",(0,d.jsx)(n.h4,{id:"record_reasoning",children:"record_reasoning"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'record_reasoning(\n *,\n step: str,\n thought: str,\n evidence: list[str] | None = None,\n conclusion: str = "",\n) -> None\n'})}),"\n",(0,d.jsx)(n.p,{children:"Buffer a reasoning/chain-of-thought step."}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"step"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsx)(n.td,{children:"Reasoning step name"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"thought"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsx)(n.td,{children:"The reasoning text/thought process"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"evidence"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"list[str] | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Supporting evidence or references"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"conclusion"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"Conclusion reached at this step"})]})]})]}),"\n",(0,d.jsx)(n.h4,{id:"record_retry",children:"record_retry"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'record_retry(\n *,\n attempt: int,\n reason: str,\n strategy: str = "retry",\n original_error: str = "",\n fallback_to: str = "",\n max_attempts: int | None = None,\n) -> None\n'})}),"\n",(0,d.jsx)(n.p,{children:"Buffer a retry or fallback event."}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"attempt"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"int"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsx)(n.td,{children:"Current attempt number (1-based)"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"reason"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsx)(n.td,{children:"Why a retry/fallback occurred"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"strategy"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'"retry"'})}),(0,d.jsxs)(n.td,{children:[(0,d.jsx)(n.code,{children:'"retry"'}),", ",(0,d.jsx)(n.code,{children:'"fallback"'}),", or ",(0,d.jsx)(n.code,{children:'"circuit_break"'})]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"original_error"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"The error that triggered the retry"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"fallback_to"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"Name of fallback target (model, agent, tool)"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"max_attempts"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"int | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Maximum attempts configured"})]})]})]}),"\n",(0,d.jsx)(n.h4,{id:"check_policy--check_policy_sync",children:"check_policy / check_policy_sync"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"# Async\nasync check_policy() -> PolicyCheckResult\n\n# Sync\ncheck_policy_sync() -> PolicyCheckResul
1t\n"})}),"\n",(0,d.jsxs)(n.p,{children:["Perform a mid-execution policy check. Returns a ",(0,d.jsx)(n.code,{children:"PolicyCheckResult"}),". Use ",(0,d.jsx)(n.code,{children:"check_policy_sync()"})," in synchronous code."]}),"\n",(0,d.jsx)(n.h3,{id:"properties",children:"Properties"}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Property"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"run_id"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsxs)(n.td,{children:["The run ID from the control plane, or ",(0,d.jsx)(n.code,{children:'""'})," if not started"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"session_id"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"The session ID passed to the constructor"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"user_id"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"The user ID passed to the constructor"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"user_group"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"The user group passed to the constructor"})]})]})]}),"\n",(0,d.jsx)(n.hr,{}),"\n",(0,d.jsx)(n.h2,{id:"observe--waxell_agent",children:"@observe / @waxell_agent"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"from waxell_observe import observe # Alias for waxell_agent\nfrom waxell_observe import waxell_agent # Original decorator (identical to observe)\n"})}),"\n",(0,d.jsxs)(n.p,{children:["Decorator that adds observability and governance to any function. ",(0,d.jsx)(n.code,{children:"@observe"})," and ",(0,d.jsx)(n.code,{children:"@waxell_agent"})," are identical -- use whichever reads better in your codebase."]}),"\n",(0,d.jsx)(n.h3,{id:"signature",children:"Signature"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'@observe(\n agent_name: str | None = None,\n workflow_name: str = "default",\n enforce_policy: bool = True,\n capture_io: bool = True,\n session_id: str = "",\n user_id: str = "",\n user_group: str = "",\n mid_execution_governance: bool = False,\n auto_grounding: bool = False,\n on_policy_block: Callable | None = None,\n client: WaxellObserveClient | None = None,\n)\n'})}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"agent_name"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Agent name. Defaults to the function name"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"workflow_name"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'"default"'})}),(0,d.jsx)(n.td,{children:"Workflow name"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"enforce_policy"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"bool"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"True"})}),(0,d.jsx)(n.td,{children:"Check policies before execution"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"capture_io"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"bool"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"True"})}),(0,d.jsx)(n.td,{children:"Capture function inputs and outputs"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"session_id"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"Session ID for grouping related runs"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"user_id"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"End-user ID for attribution and analytics"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"user_group"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"User group for authorization policies"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"mid_execution_governance"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"bool"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"False"})}),(0,d.jsxs)(n.td,{children:["Flush data and check governance on each ",(0,d.jsx)(n.code,{children:"record_step()"})," call"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"auto_grounding"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"bool"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"False"})}),(0,d.jsx)(n.td,{children:"Auto-bridge retrieval scores to grounding governance"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"on_policy_block"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"Callable | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsxs)(n.td,{children:["Callback for policy blocks. Receives ",(0,d.jsx)(n.code,{children:"PolicyViolationError"}),", returns ",(0,d.jsx)(n.code,{children:"ApprovalDecision"}),". Built-in: ",(0,d.jsx)(n.code,{children:"prompt_approval"}),", ",(0,d.jsx)(n.code,{children:"auto_approve"}),", ",(0,d.jsx)(n.code,{children:"auto_deny"})]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"client"})}
1),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"WaxellObserveClient | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Pre-configured client"})]})]})]}),"\n",(0,d.jsx)(n.h3,{id:"context-injection",children:"Context Injection"}),"\n",(0,d.jsxs)(n.p,{children:["If the decorated function has a ",(0,d.jsx)(n.code,{children:"waxell_ctx"})," parameter, a ",(0,d.jsx)(n.code,{children:"WaxellContext"})," instance is injected automatically:"]}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'@observe(agent_name="my-agent")\nasync def my_func(query: str, waxell_ctx=None) -> str:\n if waxell_ctx:\n waxell_ctx.record_llm_call(model="gpt-4o", tokens_in=100, tokens_out=50)\n waxell_ctx.record_score("relevance", 0.9)\n waxell_ctx.set_tag("source", "api")\n return "result"\n'})}),"\n",(0,d.jsx)(n.h3,{id:"example",children:"Example"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'import waxell_observe as waxell\n\[email protected](agent_name="my-agent")\nasync def chat(query: str) -> str:\n response = await openai_client.chat.completions.create(\n model="gpt-4o",\n messages=[{"role": "user", "content": query}],\n ) # auto-captured by instrumentation\n waxell.score("helpfulness", 0.9)\n waxell.tag("intent", "question")\n return response.choices[0].message.content\n# Creates a full run with LLM call, score, and tag \u2014 all auto-recorded\n'})}),"\n",(0,d.jsx)(n.h3,{id:"behavior",children:"Behavior"}),"\n",(0,d.jsxs)(n.ul,{children:["\n",(0,d.jsxs)(n.li,{children:[(0,d.jsx)(n.strong,{children:"Async functions"})," are wrapped with an async wrapper"]}),"\n",(0,d.jsxs)(n.li,{children:[(0,d.jsx)(n.strong,{children:"Sync functions"})," are wrapped with a sync wrapper that uses ",(0,d.jsx)(n.code,{children:"asyncio.run()"})," internally"]}),"\n",(0,d.jsxs)(n.li,{children:["On success, the run is completed with ",(0,d.jsx)(n.code,{children:'status="success"'})," and the captured return value"]}),"\n",(0,d.jsxs)(n.li,{children:["On exception, the run is completed with ",(0,d.jsx)(n.code,{children:'status="error"'})," and the error message; the exception is re-raised"]}),"\n"]}),"\n",(0,d.jsx)(n.hr,{}),"\n",(0,d.jsx)(n.h2,{id:"tool",children:"@tool"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"from waxell_observe import tool\n"})}),"\n",(0,d.jsxs)(n.p,{children:["Decorator that auto-records function calls as tool invocations on the current ",(0,d.jsx)(n.code,{children:"WaxellContext"}),"."]}),"\n",(0,d.jsx)(n.h3,{id:"signature-1",children:"Signature"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'@tool(name: str | None = None, tool_type: str = "function")\n'})}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"name"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Tool name. Defaults to function name"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"tool_type"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'"function"'})}),(0,d.jsxs)(n.td,{children:["Classification: ",(0,d.jsx)(n.code,{children:'"function"'}),", ",(0,d.jsx)(n.code,{children:'"vector_db"'}),", ",(0,d.jsx)(n.code,{children:'"database"'}),", ",(0,d.jsx)(n.code,{children:'"api"'})]})]})]})]}),"\n",(0,d.jsxs)(n.p,{children:['Captures: function arguments as input, return value as output, execution time, status ("ok" or "error"). Re-raises any exceptions. No-op outside a ',(0,d.jsx)(n.code,{children:"WaxellContext"}),". Works with sync and async functions."]}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'import waxell_observe as waxell\n\[email protected](tool_type="vector_db")\ndef search_index(query_vec, k: int = 5):\n distances, indices = index.search(query_vec, k)\n return {"distances": distances.tolist(), "indices": indices.tolist()}\n# Auto-records: tool_call(name="search_index", input={...}, output={...}, duration_ms=...)\n'})}),"\n",(0,d.jsx)(n.hr,{}),"\n",(0,d.jsx)(n.h2,{id:"decision",children:"@decision"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"from waxell_observe import decision\n"})}),"\n",(0,d.jsx)(n.p,{children:"Decorator that auto-records a function's return value as a decision."}),"\n",(0,d.jsx)(n.h3,{id:"signature-2",children:"Signature"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"@decision(name: str | None = None, options: list[str] | None = None)\n"})}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"name"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Decision name. Defaults to function name"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"options"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"list[str] | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Available choices"})]})]})]}),"\n",(0,d.jsxs)(n.p,{children:[(0,d.jsx)(n.strong,{children:"Return value handling:"})," ",(0,d.jsx)(n.code,{children:"dict"})," returns extract ",(0,d.jsx)(n.code,{children:"chosen"}),", ",(0,d.jsx)(n.code,{children:"reasoning"}),", ",(0,d.jsx)(n.code,{children:"confidence"}),". String returns use the string as ",(0,d.jsx)(n.code,{children:"chosen"}),"."]}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'import waxell_observe as waxell\n\[email protected](name="route_query", options=["factual", "anal
1ytical", "creative"])\nasync def classify_query(query: str) -> dict:\n response = await client.chat.completions.create(...)\n return {"chosen": "factual", "reasoning": "Direct question", "confidence": 0.92}\n# Dict return: extracts chosen, reasoning, confidence automatically\n'})}),"\n",(0,d.jsx)(n.hr,{}),"\n",(0,d.jsx)(n.h2,{id:"retrieval",children:"@retrieval"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"from waxell_observe import retrieval\n"})}),"\n",(0,d.jsx)(n.p,{children:"Decorator that auto-records function calls as retrieval operations."}),"\n",(0,d.jsx)(n.h3,{id:"signature-3",children:"Signature"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'@retrieval(source: str = "", name: str | None = None)\n'})}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"source"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsxs)(n.td,{children:["Data source name (e.g., ",(0,d.jsx)(n.code,{children:'"faiss"'}),", ",(0,d.jsx)(n.code,{children:'"pinecone"'}),")"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"name"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Override name. Defaults to function name"})]})]})]}),"\n",(0,d.jsxs)(n.p,{children:["Extracts query from the first string argument, documents from the return value, and scores from ",(0,d.jsx)(n.code,{children:'doc["score"]'})," fields."]}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'import waxell_observe as waxell\n\[email protected](source="faiss")\ndef search_documents(query: str, corpus: list) -> list[dict]:\n return [{"id": 1, "title": "Result", "score": 0.95}]\n# Auto-extracts: query from first str arg, documents from return, scores from "score" keys\n'})}),"\n",(0,d.jsx)(n.hr,{}),"\n",(0,d.jsx)(n.h2,{id:"reasoning_dec",children:"@reasoning_dec"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"from waxell_observe import reasoning_dec\n"})}),"\n",(0,d.jsx)(n.p,{children:"Decorator that auto-records a function's return value as a reasoning step."}),"\n",(0,d.jsx)(n.h3,{id:"signature-4",children:"Signature"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"@reasoning_dec(step: str | None = None)\n"})}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsx)(n.tbody,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"step"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Reasoning step name. Defaults to function name"})]})})]}),"\n",(0,d.jsxs)(n.p,{children:[(0,d.jsx)(n.strong,{children:"Return value handling:"})," ",(0,d.jsx)(n.code,{children:"dict"})," returns extract ",(0,d.jsx)(n.code,{children:"thought"}),", ",(0,d.jsx)(n.code,{children:"evidence"}),", ",(0,d.jsx)(n.code,{children:"conclusion"}),". String returns use the string as ",(0,d.jsx)(n.code,{children:"thought"}),"."]}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'import waxell_observe as waxell\n\[email protected]_dec(step="quality_check")\nasync def assess_answer(answer: str) -> dict:\n return {"thought": "Answer covers sources", "evidence": ["A cited"], "conclusion": "High quality"}\n# Dict return: extracts thought, evidence, conclusion\n'})}),"\n",(0,d.jsx)(n.hr,{}),"\n",(0,d.jsx)(n.h2,{id:"retry_dec",children:"@retry_dec"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"from waxell_observe import retry_dec\n"})}),"\n",(0,d.jsx)(n.p,{children:"Decorator that wraps a function with retry logic AND records each attempt."}),"\n",(0,d.jsx)(n.h3,{id:"signature-5",children:"Signature"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'@retry_dec(max_attempts: int = 3, strategy: str = "retry", fallback_to: str = "")\n'})}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"max_attempts"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"int"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"3"})}),(0,d.jsx)(n.td,{children:"Maximum attempts (including first)"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"strategy"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'"retry"'})}),(0,d.jsxs)(n.td,{children:[(0,d.jsx)(n.code,{children:'"retry"'}),", ",(0,d.jsx)(n.code,{children:'"fallback"'}),", or ",(0,d.jsx)(n.code,{children:'"circuit_break"'})]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"fallback_to"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"Fallback target name"})]})]})]}),"\n",(0,d.jsx)(n.p,{children:"On each failure, records a retry span. After exhausting attempts, re-raises the last exception."}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'import waxell_observe as waxell\n\[email protected]_dec(max_attempts=3, strategy="fallback", fallback_to="gpt-4o-mini")\nasync def call_llm(prompt: str) ->
1 str:\n response = await client.chat.completions.create(model="gpt-4o", messages=[...])\n return response.choices[0].message.content\n# Retries up to 3 times, records each attempt as a retry span\n'})}),"\n",(0,d.jsx)(n.hr,{}),"\n",(0,d.jsx)(n.h2,{id:"step_dec",children:"@step_dec"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"from waxell_observe import step_dec\n"})}),"\n",(0,d.jsx)(n.p,{children:"Decorator that auto-records function calls as execution steps."}),"\n",(0,d.jsx)(n.h3,{id:"signature-6",children:"Signature"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"@step_dec(name: str | None = None)\n"})}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsx)(n.tbody,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"name"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Step name. Defaults to function name"})]})})]}),"\n",(0,d.jsxs)(n.p,{children:["Records the function's return value as the step output. No-op outside a ",(0,d.jsx)(n.code,{children:"WaxellContext"}),"."]}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'import waxell_observe as waxell\n\[email protected]_dec(name="preprocess")\ndef clean_input(text: str) -> dict:\n cleaned = text.strip().lower()\n return {"original": text, "cleaned": cleaned, "length": len(cleaned)}\n# Return value becomes step output\n'})}),"\n",(0,d.jsx)(n.hr,{}),"\n",(0,d.jsx)(n.h2,{id:"waxelllangchainhandler",children:"WaxellLangChainHandler"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"from waxell_observe.integrations.langchain import WaxellLangChainHandler\n"})}),"\n",(0,d.jsxs)(n.p,{children:["Factory function that returns a LangChain ",(0,d.jsx)(n.code,{children:"BaseCallbackHandler"})," instance."]}),"\n",(0,d.jsx)(n.h3,{id:"signature-7",children:"Signature"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'WaxellLangChainHandler(\n agent_name: str,\n workflow_name: str = "default",\n client: WaxellObserveClient | None = None,\n enforce_policy: bool = True,\n auto_start_run: bool = True,\n) -> BaseCallbackHandler\n'})}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"agent_name"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsx)(n.td,{children:"Agent name"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"workflow_name"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'"default"'})}),(0,d.jsx)(n.td,{children:"Workflow name"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"client"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"WaxellObserveClient | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Pre-configured client"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"enforce_policy"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"bool"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"True"})}),(0,d.jsx)(n.td,{children:"Check policies on first callback"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"auto_start_run"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"bool"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"True"})}),(0,d.jsx)(n.td,{children:"Automatically start a run on first callback"})]})]})]}),"\n",(0,d.jsx)(n.admonition,{type:"info",children:(0,d.jsxs)(n.p,{children:["Requires ",(0,d.jsx)(n.code,{children:"langchain-core"}),". Install with ",(0,d.jsx)(n.code,{children:"pip install waxell-observe[langchain]"}),"."]})}),"\n",(0,d.jsx)(n.h3,{id:"instance-methods",children:"Instance Methods"}),"\n",(0,d.jsx)(n.h4,{id:"flush-1",children:"flush"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'async flush(\n result: dict | None = None,\n status: str = "success",\n error: str = "",\n) -> None\n'})}),"\n",(0,d.jsx)(n.p,{children:"Flush all buffered telemetry to the control plane and complete the run."}),"\n",(0,d.jsx)(n.h4,{id:"flush_sync-1",children:"flush_sync"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"flush_sync(**kwargs) -> None\n"})}),"\n",(0,d.jsxs)(n.p,{children:["Synchronous version of ",(0,d.jsx)(n.code,{children:"flush"}),". Accepts the same keyword arguments."]}),"\n",(0,d.jsx)(n.h3,{id:"instance-properties",children:"Instance Properties"}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Property"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsx)(n.tbody,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"run_id"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsxs)(n.td,{children:["The run ID from the control plane, or ",(0,d.jsx)(n.code,{children:'""'})," if no run started"]})]})})]}),"\n",(0,d.jsx)(n.h3,{id:"captured-callbacks",children:"Captured Callbacks"}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Callback"}),(0,d.jsx)(n.th,{children:"Data Captured"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"on_llm_start"})}),(0,d.jsx)(n.td,{children:"Model name, prompt preview (500 chars)"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"on_llm_end"})}),(0,d.jsx)(n.td,{children:"Token counts, cost estimate, response preview (500 chars)"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"on_chain_start"})}),(0,d.jsx)(n.td,{children:"Chain name as a step"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"on_chain_end"})}),(0,d.jsx)(n.td,{children:"Chain output"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"on_tool_start"})}),(0,d.jsxs)(n.td,{children:["Tool name as a step (prefixed ",(0,d.jsx)(n.code,{children:"tool:"}),")"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"on_tool_end"})}),(0,d.jsx)(n.td,{children:"Tool output (1000 chars)"})]})]})]}),"\n",(0,d.jsx)(n.hr,{}),"\n",(0,d.jsx)(n.h2,{id:"types",children:"Types"}),"\n",(0,d.jsx)(n.h3,{id:"runinfo",children:"RunInfo"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"from waxell_observe import RunInfo\n"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"@dataclass\nclass RunInfo:\n run_id: str\n workflow_id: str\n started_at: str\n"})}),"\n",(0,d.jsxs)(n.p,{children:["Information about a started execution run. Returned by ",(0,d.jsx)(n.code,{children:"WaxellOb
1serveClient.start_run()"}),"."]}),"\n",(0,d.jsx)(n.h3,{id:"runcompleteresult",children:"RunCompleteResult"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"from waxell_observe import RunCompleteResult\n"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'@dataclass\nclass RunCompleteResult:\n run_id: str\n duration: float | None = None\n governance_action: str = "allow"\n governance_reason: str = ""\n retry_feedback: str = ""\n max_retries: int = 0\n\n @property\n def should_retry(self) -> bool: ... # True if governance_action == "retry"\n'})}),"\n",(0,d.jsxs)(n.p,{children:["Result from completing a run, including governance info. Returned by ",(0,d.jsx)(n.code,{children:"WaxellObserveClient.complete_run()"}),"."]}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Field"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"run_id"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"(required)"}),(0,d.jsx)(n.td,{children:"The run ID"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"duration"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"float | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Run duration in seconds"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"governance_action"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'"allow"'})}),(0,d.jsx)(n.td,{children:"Post-execution governance action"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"governance_reason"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"Reason for governance action"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"retry_feedback"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"Feedback for retry attempts"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"max_retries"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"int"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"0"})}),(0,d.jsx)(n.td,{children:"Maximum retry attempts allowed"})]})]})]}),"\n",(0,d.jsx)(n.h3,{id:"policycheckresult",children:"PolicyCheckResult"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"from waxell_observe import PolicyCheckResult\n"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'@dataclass\nclass PolicyCheckResult:\n action: str # "allow", "block", "warn", "throttle", "retry"\n reason: str = ""\n metadata: dict = field(default_factory=dict)\n evaluations: list = field(default_factory=list)\n\n @property\n def allowed(self) -> bool: ... # True if action in ("allow", "warn")\n\n @property\n def blocked(self) -> bool: ... # True if action in ("block", "throttle")\n\n @property\n def should_retry(self) -> bool: ... # True if action == "retry"\n'})}),"\n",(0,d.jsxs)(n.p,{children:["Result of a policy check. Returned by ",(0,d.jsx)(n.code,{children:"WaxellObserveClient.check_policy()"})," and ",(0,d.jsx)(n.code,{children:"WaxellContext.check_policy()"}),"."]}),"\n",(0,d.jsx)(n.h3,{id:"llmcallinfo",children:"LlmCallInfo"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"from waxell_observe import LlmCallInfo\n"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'@dataclass\nclass LlmCallInfo:\n model: str\n tokens_in: int\n tokens_out: int\n cost: float = 0.0\n task: str = ""\n prompt_preview: str = ""\n response_preview: str = ""\n'})}),"\n",(0,d.jsx)(n.p,{children:"Typed representation of an LLM API call. Useful for constructing call records programmatically."}),"\n",(0,d.jsx)(n.h3,{id:"promptinfo",children:"PromptInfo"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"from waxell_observe import PromptInfo\n"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'@dataclass\nclass PromptInfo:\n name: str\n version: int\n prompt_type: str # "text" or "chat"\n content: object # str for text, list[dict] for chat\n config: dict = field(default_factory=dict)\n labels: list = field(default_factory=list)\n\n def compile(self, **variables: str) -> object: ...\n'})}),"\n",(0,d.jsxs)(n.p,{children:["A prompt version retrieved from the control plane. Returned by ",(0,d.jsx)(n.code,{children:"WaxellOb
1serveClient.get_prompt()"}),"."]}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Field"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"name"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"Prompt name"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"version"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"int"})}),(0,d.jsx)(n.td,{children:"Version number"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"prompt_type"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsxs)(n.td,{children:[(0,d.jsx)(n.code,{children:'"text"'})," for plain text prompts, ",(0,d.jsx)(n.code,{children:'"chat"'})," for chat message prompts"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"content"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str | list[dict]"})}),(0,d.jsxs)(n.td,{children:["Prompt content. A string for text prompts, a list of ",(0,d.jsx)(n.code,{children:'{"role": ..., "content": ...}'})," message dicts for chat prompts"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"config"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"dict"})}),(0,d.jsxs)(n.td,{children:["Model configuration (e.g. ",(0,d.jsx)(n.code,{children:"temperature"}),", ",(0,d.jsx)(n.code,{children:"max_tokens"}),", ",(0,d.jsx)(n.code,{children:"model"}),")"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"labels"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"list[str]"})}),(0,d.jsxs)(n.td,{children:["Labels attached to this version (e.g. ",(0,d.jsx)(n.code,{children:'["production", "latest"]'}),")"]})]})]})]}),"\n",(0,d.jsx)(n.h4,{id:"compile",children:"compile"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"prompt.compile(**variables: str) -> str | list[dict]\n"})}),"\n",(0,d.jsxs)(n.p,{children:["Render the prompt by replacing ",(0,d.jsx)(n.code,{children:"{{variable}}"})," placeholders in the content."]}),"\n",(0,d.jsxs)(n.ul,{children:["\n",(0,d.jsxs)(n.li,{children:[(0,d.jsx)(n.strong,{children:"Text prompts:"})," Returns a string with all ",(0,d.jsx)(n.code,{children:"{{variable}}"})," placeholders replaced."]}),"\n",(0,d.jsxs)(n.li,{children:[(0,d.jsx)(n.strong,{children:"Chat prompts:"})," Returns a list of message dicts with ",(0,d.jsx)(n.code,{children:"{{variable}}"})," placeholders replaced in each message's ",(0,d.jsx)(n.code,{children:"content"})," field."]}),"\n"]}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Example:"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'# Text prompt\nprompt = await client.get_prompt("summarizer", label="production")\nrendered = prompt.compile(topic="AI safety", length="short")\n# rendered: "Summarize the following about AI safety in short form: ..."\n\n# Chat prompt\nprompt = await client.get_prompt("assistant", label="production")\nmessages = prompt.compile(user_query="What is RAG?")\n# messages: [{"role": "system", "content": "..."}, {"role": "user", "content": "What is RAG?"}]\n\n# Use config for model parameters\nresponse = openai.chat.completions.create(\n model=prompt.config.get("model", "gpt-4o"),\n messages=messages,\n temperature=prompt.config.get("temperature", 0.7),\n)\n'})}),"\n",(0,d.jsx)(n.h3,{id:"observeconfig",children:"ObserveConfig"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"from waxell_observe import ObserveConfig\n"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'@dataclass\nclass ObserveConfig:\n api_url: str = ""\n api_key: str = ""\n otel_endpoint: str = ""\n debug: bool = False\n capture_content: bool = False\n prompt_guard: bool = False\n prompt_guard_server: bool = False\n prompt_guard_action: str = "block"\n instrument_infra: bool = True\n infra_exclude: str = ""\n\n @classmethod\n def from_env(cls) -> ObserveConfig: ...\n\n @classmethod\n def from_cli_config(cls, config_path: Path | None = None) -> ObserveConfig: ...\n\n @property\n def is_configured(self) -> bool: ...\n'})}),"\n",(0,d.jsxs)(n.p,{children:["Configuration data class. Used internally by ",(0,d.jsx)(n.code,{children:"WaxellOb
1serveClient"})," to resolve settings."]}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Field"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"api_url"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"Waxell API URL"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"api_key"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"Waxell API key"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"otel_endpoint"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"Explicit OTel collector endpoint"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"debug"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"bool"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"False"})}),(0,d.jsx)(n.td,{children:"Enable debug logging"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"capture_content"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"bool"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"False"})}),(0,d.jsx)(n.td,{children:"Include prompt/response content in traces"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"prompt_guard"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"bool"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"False"})}),(0,d.jsx)(n.td,{children:"Enable client-side prompt guard"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"prompt_guard_server"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"bool"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"False"})}),(0,d.jsx)(n.td,{children:"Enable server-side prompt guard"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"prompt_guard_action"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'"block"'})}),(0,d.jsxs)(n.td,{children:["Action on violations: ",(0,d.jsx)(n.code,{children:'"block"'}),", ",(0,d.jsx)(n.code,{children:'"warn"'}),", or ",(0,d.jsx)(n.code,{children:'"redact"'})]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"instrument_infra"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"bool"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"True"})}),(0,d.jsx)(n.td,{children:"Enable infrastructure library instrumentation"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"infra_exclude"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"Comma-delimited list of infra libraries to exclude"})]})]})]}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Class Method"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"from_env()"})}),(0,d.jsxs)(n.td,{children:["Load from environment variables (",(0,d.jsx)(n.code,{children:"WAXELL_API_URL"}),"/",(0,d.jsx)(n.code,{children:"WAXELL_API_KEY"})," or ",(0,d.jsx)(n.code,{children:"WAX_API_URL"}),"/",(0,d.jsx)(n.code,{children:"WAX_API_KEY"}),")"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"from_cli_config(config_path=None)"})}),(0,d.jsxs)(n.td,{children:["Load from CLI config file (default: ",(0,d.jsx)(n.code,{children:"~/.waxell/config"}),")"]})]})]})]}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Property"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsx)(n.tbody,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"is_configured"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"bool"})}),(0,d.jsxs)(n.td,{children:[(0,d.jsx)(n.code,{children:"True"})," if both ",(0,d.jsx)(n.code,{children:"api_url"})," and ",(0,d.jsx)(n.code,{children:"api_key"})," are non-empty"]})]})})]}),"\n",(0,d.jsx)(n.h3,{id:"approvaldecision",children:"ApprovalDecision"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"from waxell_observe import ApprovalDecision\n"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:'@dataclass\nclass ApprovalDecision:\n approved: bool\n approver: str = ""\n timed_out: bool = False\n elapsed_seconds: float | None = None\n'})}),"\n",(0,d.jsxs)(n.p,{children:["Return type from ",(0,d.jsx)(n.code,{children:"on_policy_block"})," handlers. Tells the decorator whether to retry the function (",(0,d.jsx)(n.code,{children:"approved=True"}),") or propagate the ",(0,d.jsx)(n.code,{children:"PolicyViolationError"}),"."]}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Field"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Default"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"approved"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"bool"})}),(0,d.jsx)(n.td,{children:"required"}),(0,d.jsx)(n.td,{children:"Whether to proceed with execution"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"approver"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:'""'})}),(0,d.jsx)(n.td,{children:"Who approved (email, username, system)"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"timed_out"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"bool"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"False"})}),(0,d.jsx)(n.td,{children:"Whether the approval window expired"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"elapsed_seconds"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"float | None"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"None"})}),(0,d.jsx)(n.td,{children:"Time from block to decision"})]})]})]}),"\n",(0,d.jsx)(n.h3,{id:"humanturn",children:"HumanTurn"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"from waxell_observe import HumanTurn\n"})}),"\n",(0,d.jsxs)(n.p,{children:["Context manager returned by ",(0,d.jsx)(n.code,{children:"waxell.human_turn()"}),". Records a human interaction as a timed IO span when it exits."]}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Method"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"set_response(response: str)"})}),(0,d.jsx)(n.td,{children:"Record what the human replied"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"__enter__()"})}),(0,d.jsx)(n.td,{children:"Start timing"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"__exit__()"})}),(0,d.jsx)(n.td,{children:"Record the span with elapsed time"})]})]})]}),"\n",(0,d.jsx)(n.hr,{}),"\n",(0,d.jsx)(n.h2,{id:"errors",children:"Errors"}),"\n",(0,d.jsxs)(n.p,{children:["All errors inherit from ",(0,d.jsx)(n.code,{children:"ObserveError"}),", which inherits from ",(0,d.jsx)(n.code,{children:"Exception"}),"."]}),"\n",(0,d.jsx)(n.h3,{id:"observeerror",children:"ObserveError"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"from waxell_observe import ObserveError\n"})}),"\n",(0,d.jsx)(n.p,{children:"Base error class for all waxell-observe errors."}),"\n",(0,d.jsx)(n.h3,{id:"policyviolationerror",children:"PolicyViolationError"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"from waxell_observe import PolicyViolationError\n"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"class PolicyViolationError(ObserveError):\n def __init__(self, message: str, policy_result=None): ...\n policy_result: PolicyCheckResult | None\n"})}),"\n",(0,d.jsxs)(n.p,{children:["Raised when a policy check blocks execution (action is ",(0,d.jsx)(n.code,{children:'"block"'})," or ",(0,d.jsx)(n.code,{children:'"throttle"'}),")."]}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Attribute"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsx)(n.tbody,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"policy_result"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"PolicyCheckResult | None"})}),(0,d.jsx)(n.td,{children:"The full policy check result"})]})})]}),"\n",(0,d.jsx)(n.h3,{id:"configurationerror",children:"ConfigurationError"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"from waxell_observe import ConfigurationError\n"})}),"\n",(0,d.jsxs)(n.p,{children:["Raised when the client is not properly configured. Inherits from ",(0,d.jsx)(n.code,{children:"ObserveError"}),"."]}),"\n",(0,d.jsx)(n.hr,{}),"\n",(0,d.jsx)(n.h2,{id:"functions",children:"Functions"}),"\n",(0,d.jsx)(n.h3,{id:"estimate_cost",children:"estimate_cost"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"from waxell_observe.cost import estimate_cost\n"})}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-python",children:"estimate_cost(model: str, tokens_in: int, tokens_out: int) -> float\n"})}),"\n",(0,d.jsxs)(n.p,{children:["Estimate the USD cost of an LLM call. Uses exact match first, then prefix matching for versioned model names. Returns ",(0,d.jsx)(n.code,{children:"0.0"})," for unknown models."]}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Parameter"}),(0,d.jsx)(n.th,{children:"Type"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"model"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"str"})}),(0,d.jsx)(n.td,{children:"Model name or prefix"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"tokens_in"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"int"})}),(0,d.jsx)(n.td,{children:"Input token count"})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"tokens_out"})}),(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"int"})}),(0,d.jsx)(n.td,{children:"Output token count"})]})]})]}),"\n",(0,d.jsx)(n.hr,{}),"\n",(0,d.jsx)(n.h2,{id:"configuration-resolution",children:"Configuration Resolution"}),"\n",(0,d.jsx)(n.p,{children:"The SDK resolves configuration from multiple sources, in order of precedence (highest to lowest):"}),"\n",(0,d.jsxs)(n.ol,{children:["\n",(0,d.jsxs)(n.li,{children:[(0,d.jsx)(n.strong,{children:"Explicit constructor arguments"}
1)," -- ",(0,d.jsx)(n.code,{children:'WaxellObserveClient(api_url="...", api_key="...")'})]}),"\n",(0,d.jsxs)(n.li,{children:[(0,d.jsx)(n.strong,{children:"Global config"})," -- ",(0,d.jsx)(n.code,{children:"WaxellObserveClient.configure(...)"})," or ",(0,d.jsx)(n.code,{children:"waxell_observe.init(...)"})]}),"\n",(0,d.jsxs)(n.li,{children:[(0,d.jsx)(n.strong,{children:"CLI config file"})," -- ",(0,d.jsx)(n.code,{children:"~/.waxell/config"})," (INI format)"]}),"\n",(0,d.jsxs)(n.li,{children:[(0,d.jsx)(n.strong,{children:"Environment variables"})," -- ",(0,d.jsx)(n.code,{children:"WAXELL_API_URL"})," / ",(0,d.jsx)(n.code,{children:"WAXELL_API_KEY"})," (or ",(0,d.jsx)(n.code,{children:"WAX_API_URL"})," / ",(0,d.jsx)(n.code,{children:"WAX_API_KEY"}),")"]}),"\n"]}),"\n",(0,d.jsx)(n.p,{children:(0,d.jsx)(n.strong,{children:"Environment variables:"})}),"\n",(0,d.jsxs)(n.table,{children:[(0,d.jsx)(n.thead,{children:(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.th,{children:"Variable"}),(0,d.jsx)(n.th,{children:"Description"})]})}),(0,d.jsxs)(n.tbody,{children:[(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"WAXELL_API_URL"})}),(0,d.jsxs)(n.td,{children:["Control plane URL (e.g. ",(0,d.jsx)(n.code,{children:"https://acme.waxell.dev"}),")"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"WAXELL_API_KEY"})}),(0,d.jsxs)(n.td,{children:["API key (e.g. ",(0,d.jsx)(n.code,{children:"wax_sk_abc123"}),")"]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"WAX_API_URL"})}),(0,d.jsxs)(n.td,{children:["Alias for ",(0,d.jsx)(n.code,{children:"WAXELL_API_URL"})]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"WAX_API_KEY"})}),(0,d.jsxs)(n.td,{children:["Alias for ",(0,d.jsx)(n.code,{children:"WAXELL_API_KEY"})]})]}),(0,d.jsxs)(n.tr,{children:[(0,d.jsx)(n.td,{children:(0,d.jsx)(n.code,{children:"WAXELL_OBSERVE"})}),(0,d.jsxs)(n.td,{children:["Kill switch. Set to ",(0,d.jsx)(n.code,{children:"false"}),", ",(0,d.jsx)(n.code,{children:"0"}),", or ",(0,d.jsx)(n.code,{children:"no"})," to disable ",(0,d.jsx)(n.code,{children:"init()"})]})]})]})]}),"\n",(0,d.jsx)(n.hr,{}),"\n",(0,d.jsx)(n.h2,{id:"next-steps",children:"Next Steps"}),"\n",(0,d.jsxs)(n.ul,{children:["\n",(0,d.jsxs)(n.li,{children:[(0,d.jsx)(n.a,{href:"./endpoints",children:"REST API Reference"})," -- Direct HTTP API usage"]}),"\n",(0,d.jsxs)(n.li,{children:[(0,d.jsx)(n.a,{href:"../quickstart",children:"Quickstart"})," -- Get started in 5 minutes"]}),"\n",(0,d.jsxs)(n.li,{children:[(0,d.jsx)(n.a,{href:"../installation",children:"Installation & Configuration"})," -- Setup guide"]}),"\n"]})]})}function a(e={}){const{wrapper:n}={...(0,c.R)(),...e.components};return n?(0,d.jsx)(n,{...e,children:(0,d.jsx)(h,{...e})}):h(e)}},28453(e,n,r){r.d(n,{R:()=>l,x:()=>i});var s=r(96540);const d={},c=s.createContext(d);function l(e){const n=s.useContext(c);return s.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function i(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(d):e.components||d:l(e.components),s.createElement(c.Provider,{value:n},e.children)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.