b3-prosaic-runtime 0.8.1__py3-none-any.whl

prosaic_runtime/anthropic_stream.py

@@ -0,0 +1,179 @@
+"""Strict native SSE assembly; tool blocks leave this module only when complete."""
+import time
+
+from .accounting_capture import strict_json
+from .anthropic import parse_message
+from .anthropic_usage import UsageSnapshots
+from .events import check_cancelled, emit
+from .openai_compatible import _http_status, _raw_response_headers
+from .types import Result
+from .http_bounds import LimitExceeded, set_response_timeout
+
+
+class StreamState:
+    def __init__(self, on_text):
+        self.message = None
+        self.blocks = []
+        self.active = None
+        self.arguments = ''
+        self.delta_seen = False
+        self.stopped = False
+        self.on_text = on_text
+        self.usage = UsageSnapshots()
+
+    def push(self, event):
+        if not isinstance(event, dict) or not isinstance(event.get('type'), str):
+            raise ValueError('invalid stream event')
+        kind = event['type']
+        if self.stopped:
+            raise ValueError('event after message_stop')
+        if kind == 'ping':
+            return
+        if kind == 'message_start':
+            message = event.get('message')
+            if (self.message is not None or not isinstance(message, dict) or
+                    message.get('type') != 'message' or message.get('role') != 'assistant' or
+                    message.get('content') != [] or message.get('stop_reason') is not None or
+                    not isinstance(message.get('id'), str) or not message['id'] or
+                    not isinstance(message.get('model'), str) or not message['model']):
+                raise ValueError('invalid message_start')
+            self.message = {**message, 'content': self.blocks}
+            self.usage.update(message.get('usage'))
+            return
+        if self.message is None:
+            raise ValueError('missing message_start')
+        if kind == 'content_block_start':
+            index, block = event.get('index'), event.get('content_block')
+            if (self.delta_seen or self.active is not None or type(index) is not int or
+                    index != len(self.blocks) or not isinstance(block, dict)):
+                raise ValueError('invalid block start')
+            if block.get('type') == 'text' and isinstance(block.get('text'), str):
+                if block['text']:
+                    self.on_text(block['text'])
+            elif block.get('type') == 'tool_use' and type(block.get('input')) is dict:
+                if block['input']:
+                    raise ValueError('stream tool input must start empty')
+            else:
+                raise ValueError('unsupported content block')
+            self.blocks.append(dict(block))
+            self.active, self.arguments = index, ''
+            return
+        if kind in {'content_block_delta', 'content_block_stop'}:
+            index = event.get('index')
+            if type(index) is not int or self.active is None or index != self.active or self.delta_seen:
+                raise ValueError('inactive block')
+            block = self.blocks[index]
+            if kind == 'content_block_stop':
+                if block['type'] == 'tool_use' and self.arguments:
+                    value = strict_json(self.arguments)
+                    if type(value) is not dict:
+                        raise ValueError('tool input must be an object')
+                    block['input'] = value
+                self.active, self.arguments = None, ''
+                return
+            delta = event.get('delta')
+            if not isinstance(delta, dict):
+                raise ValueError('invalid delta')
+            if (block['type'] == 'text' and delta.get('type') == 'text_delta' and
+                    isinstance(delta.get('text'), str)):
+                block['text'] += delta['text']
+                if delta['text']:
+                    self.on_text(delta['text'])
+            elif (block['type'] == 'tool_use' and delta.get('type') == 'input_json_delta' and
+                    isinstance(delta.get('partial_json'), str)):
+                self.arguments += delta['partial_json']
+            else:
+                raise ValueError('unsupported block delta')
+            return
+        if kind == 'message_delta':
+            delta = event.get('delta')
+            if self.active is not None or not isinstance(delta, dict):
+                raise ValueError('invalid message delta')
+            if set(delta) - {'stop_reason', 'stop_sequence'}:
+                raise ValueError('unsupported message delta')
+            previous = self.message.get('stop_reason')
+            stop = delta.get('stop_reason')
+            if previous is not None and stop is not None and previous != stop:
+                raise ValueError('conflicting stop reason')
+            self.message.update(delta)
+            usage = event.get('usage')
+            if usage is not None:
+                if not isinstance(usage, dict) or not isinstance(self.message.get('usage', {}), dict):
+                    raise ValueError('invalid usage')
+                self.usage.update(usage)
+                self.message['usage'] = self.usage.raw
+            self.delta_seen = True
+            return
+        if kind == 'message_stop':
+            if self.active is not None or not self.delta_seen or self.message.get('stop_reason') is None:
+                raise ValueError('incomplete message')
+            self.stopped = True
+            return
+        # Unknown consequential events cannot be assumed to preserve execution semantics.
+        raise ValueError('unsupported stream event')
+
+
+def _emit_text(text):
+    emit('text_delta', text=text)
+
+
+def read_anthropic_turn(response, deadline, *, on_text=_emit_text):
+    state = StreamState(on_text)
+    data, event_name = [], None
+    status, headers = _http_status(response), _raw_response_headers(response)
+
+    def flush():
+        nonlocal data, event_name
+        if data:
+            event = strict_json('\n'.join(data))
+            if event_name is not None and (not isinstance(event, dict) or event.get('type') != event_name):
+                raise ValueError('SSE event name mismatch')
+            state.push(event)
+        elif event_name is not None:
+            raise ValueError('SSE event missing data')
+        data, event_name = [], None
+
+    try:
+        while True:
+            check_cancelled()
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise TimeoutError('stream deadline')
+            # Reset the socket timeout to the remaining invocation budget before each read.
+            set_response_timeout(response, remaining)
+            raw = response.readline()
+            if not raw:
+                if data or event_name is not None:
+                    raise ValueError('unterminated SSE event')
+                break
+            line = raw.decode('utf-8', errors='strict').rstrip('\r\n')
+            if not line:
+                flush()
+            elif line.startswith(':'):
+                continue
+            else:
+                field, separator, value = line.partition(':')
+                if value.startswith(' '):
+                    value = value[1:]
+                if field == 'event':
+                    if event_name is not None:
+                        raise ValueError('duplicate SSE event name')
+                    event_name = value
+                elif field == 'data':
+                    data.append(value if separator else '')
+        if not state.stopped:
+            raise ValueError('missing message_stop')
+        turn = parse_message(state.message, streamed=True, http_status=status, headers=headers,
+                             usage_conflict=state.usage.conflict)
+        if not isinstance(turn, Result):
+            turn.previewed = True
+        return turn
+    except (UnicodeError, ValueError, TypeError, RecursionError) as exc:
+        # Size-limit exceptions are host guards, not malformed provider messages.
+        if isinstance(exc, LimitExceeded):
+            raise
+        message = state.message or {}
+        return Result(1, '', 'Malformed or unsupported Anthropic stream', metadata={
+            'provider': 'anthropic', 'provider_error_code': 'malformed_response', 'streamed': True,
+            'http_status': status, 'raw_response_metadata': {
+                k: message[k] for k in ('id', 'model', 'usage', 'stop_reason') if k in message}})

prosaic_runtime/anthropic_usage.py

@@ -0,0 +1,96 @@
+"""Anthropic token evidence, with cache-write costs explicitly unsupported."""
+from .accounting import _quantity, normalize_usage
+
+TOKEN_FIELDS = ('input_tokens', 'output_tokens', 'cache_read_input_tokens', 'cache_creation_input_tokens')
+
+
+def _zero_details(value):
+    if value is None:
+        return True
+    if type(value) is dict:
+        return all(_zero_details(v) for v in value.values())
+    return type(value) is int and value == 0
+
+
+def normalize_anthropic_usage(raw):
+    result = normalize_usage(None)
+    if raw is None:
+        return result
+    if type(raw) is not dict:
+        return {**result, 'status': 'untrusted'}
+    for key in TOKEN_FIELDS:
+        if key in raw and not _quantity(raw[key]):
+            return {**result, 'status': 'untrusted'}
+    result['output_tokens'] = raw.get('output_tokens')
+    result['cached_input_tokens'] = raw.get('cache_read_input_tokens')
+    if 'input_tokens' in raw:
+        inp = sum(raw.get(k, 0) for k in ('input_tokens', 'cache_read_input_tokens', 'cache_creation_input_tokens'))
+        if not _quantity(inp):
+            return {**result, 'status': 'untrusted'}
+        result['input_tokens'] = inp
+    if result['input_tokens'] is not None and result['output_tokens'] is not None:
+        total = result['input_tokens'] + result['output_tokens']
+        if not _quantity(total):
+            return {**result, 'status': 'untrusted'}
+        result.update(total_tokens=total, status='reported')
+    # Cache-write pricing cannot be represented by the existing rate-card contract.
+    unsupported = bool(raw.get('cache_creation_input_tokens', 0))
+    if raw.get('service_tier') not in (None, 'standard') or raw.get('inference_geo') not in (None, 'global'):
+        unsupported = True
+    for key, value in raw.items():
+        if key not in TOKEN_FIELDS and key not in {'service_tier', 'inference_geo'} and not _zero_details(value):
+            unsupported = True
+    if unsupported:
+        result['status'] = 'unsupported'
+    return result
+
+
+class UsageSnapshots:
+    """Merge cumulative event snapshots; decreases invalidate accounting evidence."""
+    def __init__(self):
+        self.raw = None
+        self.conflict = False
+
+    def update(self, value):
+        if value is None:
+            return
+        if type(value) is not dict:
+            self.conflict = True
+            return
+        previous = self.raw or {}
+        if _snapshot_conflict(previous, value):
+            self.conflict = True
+        for key in TOKEN_FIELDS:
+            if key in value:
+                new, old = value[key], previous.get(key)
+                if not _quantity(new) or (old is not None and (not _quantity(old) or new < old)):
+                    self.conflict = True
+        self.raw = _merge_snapshots(previous, value)
+
+    def normalized(self):
+        usage = normalize_anthropic_usage(self.raw)
+        return {**usage, 'status': 'untrusted'} if self.conflict else usage
+
+
+def _snapshot_conflict(previous, current):
+    for key in previous.keys() & current.keys():
+        old, new = previous[key], current[key]
+        if type(old) is dict and type(new) is dict:
+            if _snapshot_conflict(old, new):
+                return True
+        elif _quantity(old) and _quantity(new):
+            if new < old:
+                return True
+        elif old != new:
+            return True
+    return False
+
+
+def _merge_snapshots(previous, current):
+    merged = dict(previous)
+    for key, value in current.items():
+        if type(value) is dict and type(previous.get(key)) is dict:
+            merged[key] = _merge_snapshots(previous[key], value)
+        else:
+            merged[key] = value
+    return merged

prosaic_runtime/artifacts.py

@@ -0,0 +1,56 @@
+"""Use Prosaic's inspection contract as the sole agent-definition parser."""
+from dataclasses import dataclass
+from pathlib import Path
+from collections.abc import Mapping
+import hashlib
+import json
+import subprocess
+
+
+@dataclass(frozen=True)
+class ProsaicArtifact:
+    id: str
+    type: str
+    frontmatter: dict
+    body: str
+    resources: tuple[dict, ...] = ()
+
+    @classmethod
+    def from_inspection(cls, data: Mapping):
+        if data.get("type") not in {"subagent", "command"}:
+            raise ValueError("execution requires a Prosaic subagent or command artifact")
+        if not isinstance(data.get("id"), str) or not data["id"]:
+            raise ValueError("inspection artifact id is required")
+        if not isinstance(data.get("frontmatter"), dict) or not isinstance(data.get("body"), str):
+            raise ValueError("invalid Prosaic inspection output")
+        resources = data.get("resources", [])
+        if not isinstance(resources, list):
+            raise ValueError("resources must be a list")
+        for item in resources:
+            if not isinstance(item, dict) or not isinstance(item.get("relPath"), str) or not isinstance(item.get("content"), str):
+                raise ValueError("invalid bundled resource")
+            path = Path(item["relPath"])
+            if path.is_absolute() or ".." in path.parts:
+                raise ValueError("resource path escapes bundle")
+        return cls(data["id"], data["type"], dict(data["frontmatter"]), data["body"], tuple(resources))
+
+    def render(self, arguments: str = "") -> str:
+        body = self.body.replace("{{args}}", arguments) if "{{args}}" in self.body else self.body + ("\n\n## Arguments\n" + arguments if arguments else "")
+        for resource in self.resources:
+            body += f"\n\n## Bundled resource: {resource['relPath']}\n{resource['content']}"
+        return body
+
+    @property
+    def digest(self):
+        raw = json.dumps({"id": self.id, "type": self.type, "frontmatter": self.frontmatter, "body": self.body, "resources": self.resources}, sort_keys=True).encode()
+        return hashlib.sha256(raw).hexdigest()
+
+
+def inspect_artifact(artifact_id: str, source: Path, *, executable="prosaic", timeout_s=30) -> ProsaicArtifact:
+    result = subprocess.run(
+        [executable, "inspect", artifact_id, "--source", str(source.resolve())],
+        cwd=source.resolve().parent, capture_output=True, text=True, timeout=timeout_s, check=False,
+    )
+    if result.returncode:
+        raise ValueError(f"Prosaic inspection failed: {result.stderr.strip()}")
+    return ProsaicArtifact.from_inspection(json.loads(result.stdout))

prosaic_runtime/budgets.py

@@ -0,0 +1,67 @@
+"""Invocation-local allowances; counts are dispatch attempts, not estimates."""
+
+
+class InvocationBudgetExceeded(Exception):
+    REASONS = frozenset({'provider_request_limit', 'tool_call_limit', 'token_limit', 'usage_unknown'})
+
+    def __init__(self, reason):
+        if reason not in self.REASONS:
+            raise ValueError('unknown invocation budget reason')
+        self.reason = reason
+        super().__init__(reason)
+
+
+class InvocationBudget:
+    def __init__(self, policy):
+        self.policy = policy
+        self.provider_requests = self.tool_calls = self.reported_tokens = 0
+        self.usage_complete = True
+
+    @property
+    def enabled(self):
+        return any(value is not None for value in (self.policy.max_provider_requests,
+            self.policy.max_tool_calls, self.policy.max_reported_tokens))
+
+    def metadata(self):
+        return {'provider_requests': self.provider_requests, 'tool_calls': self.tool_calls,
+                'reported_tokens': self.reported_tokens, 'usage_complete': self.usage_complete}
+
+    def _check_reported_allowance(self):
+        self.validate_terminal_usage()
+        if (self.policy.max_reported_tokens is not None and
+                self.reported_tokens >= self.policy.max_reported_tokens):
+            raise InvocationBudgetExceeded('token_limit')
+
+    def _reserve(self, name, cap, reason):
+        if cap is not None and getattr(self, name) >= cap:
+            raise InvocationBudgetExceeded(reason)
+        setattr(self, name, getattr(self, name) + 1)
+
+    def _check_provider(self):
+        self._check_reported_allowance()
+        cap = self.policy.max_provider_requests
+        if cap is not None and self.provider_requests >= cap:
+            raise InvocationBudgetExceeded('provider_request_limit')
+
+    def before_provider(self):
+        self._check_provider()
+        self._reserve('provider_requests', self.policy.max_provider_requests, 'provider_request_limit')
+
+    def before_tool(self):
+        self._check_reported_allowance()
+        self._reserve('tool_calls', self.policy.max_tool_calls, 'tool_call_limit')
+
+    def record_usage(self, usage):
+        if type(usage) is not int or usage < 0:
+            self.usage_complete = False
+        else:
+            self.reported_tokens += usage
+        self.validate_terminal_usage()
+
+    def validate_terminal_usage(self):
+        cap = self.policy.max_reported_tokens
+        if cap is not None:
+            if not self.usage_complete:
+                raise InvocationBudgetExceeded('usage_unknown')
+            if self.reported_tokens > cap:
+                raise InvocationBudgetExceeded('token_limit')

prosaic_runtime/cli.py

@@ -0,0 +1,153 @@
+"""Small CLI; stdout is reserved for the requested machine output."""
+import argparse
+from dataclasses import asdict
+import json
+import os
+import subprocess
+import sys
+from .runtime import ProsaicRuntime
+from .policy import RunPolicy
+from .config import RuntimeConfig
+from .console import Progress
+from .diagnostics import doctor, smoke, failure_hint, conformance
+from .accounting import ExecutionContext, RateCard
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    mode = argv.pop(0) if argv and argv[0] in {"doctor", "smoke", "preflight", "conformance"} else "run"
+    parser = argparse.ArgumentParser(prog="prosaic-runtime")
+    if mode == "run":
+        parser.add_argument("artifact", help="Prosaic artifact identifier (also: doctor or smoke subcommands)")
+    if mode == 'preflight':
+        target = parser.add_mutually_exclusive_group(required=True)
+        target.add_argument('--agent', help='Prosaic artifact identifier to check without inference')
+        target.add_argument('--all-tools', action='store_true', help='check every registered/configured tool')
+    if mode == 'run':
+        parser.add_argument('--initial-tool', help='require this granted tool as the first native call')
+        for name in ('application_id', 'tenant_id', 'billing_account_id', 'actor_id', 'project_id', 'request_id', 'run_id', 'invocation_id', 'parent_invocation_id'):
+            parser.add_argument('--' + name.replace('_', '-'), help='trusted execution attribution; omitted IDs use defaults')
+        parser.add_argument('--accounting-dsn-env', help='environment variable holding the accounting PostgreSQL DSN; requires separately installed adapter')
+        parser.add_argument('--accounting-namespace', help='persistent deployment namespace')
+        parser.add_argument('--accounting-environment', help='isolated environment, e.g. production or sandbox')
+        parser.add_argument('--accounting-rate-card', help='explicit JSON rate card for internal estimates')
+        parser.add_argument('--accounting-provider', choices=('openai-compatible', 'anthropic'),
+                            help='accounting provider identity; defaults to openai-compatible and must match the selected endpoint')
+    parser.add_argument("--source", default=".prosaic")
+    parser.add_argument("--config", help="YAML configuration (default: prosaic-runtime.yaml, then prosaic-runtime.yml)")
+    parser.add_argument("--arguments", default="")
+    parser.add_argument("--cwd", default=".")
+    parser.add_argument("--allow-tool", action="append", default=[])
+    parser.add_argument("--read-root", action="append", default=[])
+    parser.add_argument("--write-path", action="append", default=[])
+    parser.add_argument("--forbid-root", action="append", default=[])
+    parser.add_argument("--timeout", type=float, help="override YAML limits.timeout_s")
+    parser.add_argument("--max-tool-rounds", type=int, help="override YAML limits.max_tool_rounds")
+    output = parser.add_mutually_exclusive_group()
+    output.add_argument("--events", action="store_true", help="emit JSONL events followed by result")
+    output.add_argument("--output", choices=("json", "text"), default="json")
+    parser.add_argument("--quiet", action="store_true", help="suppress stderr progress (errors remain visible)")
+    if mode != "run":
+        parser.add_argument("--profile", help="endpoint profile; defaults to default_profile")
+    if mode == "doctor":
+        parser.add_argument("--inference", action="store_true", help="opt in to one model request (may incur charges)")
+    if mode == "smoke":
+        parser.add_argument("--live", action="store_true", required=True, help="explicitly authorize live model calls")
+    if mode == 'conformance':
+        parser.add_argument('--live', action='store_true', help='explicitly authorize bounded provider calls')
+    args = parser.parse_args(argv)
+    def emit(event):
+        print(json.dumps(event), flush=True)
+    try:
+        config = RuntimeConfig.load(args.config)
+        policy = RunPolicy(frozenset(args.allow_tool), tuple(args.read_root), tuple(args.write_path),
+                           tuple(args.forbid_root),
+                           args.timeout if args.timeout is not None else config.limits.timeout_s,
+                           args.max_tool_rounds if args.max_tool_rounds is not None else config.limits.max_tool_rounds,
+                           initial_tool=getattr(args, 'initial_tool', None))
+        with Progress(args.quiet or args.events) as progress:
+            sink = emit if args.events else progress
+            if mode == 'preflight':
+                runtime = ProsaicRuntime(config, source=args.source)
+                report = runtime.preflight(args.agent, all_tools=args.all_tools, cwd=args.cwd, policy=policy)
+                if args.output == 'text':
+                    print(f"preflight: {'passed' if report['ok'] else 'failed'}")
+                    for name, check in report['checks'].items():
+                        print(f"{name}: {check['status']} — {check['message']}")
+                else:
+                    emit(report)
+                return 0 if report['ok'] else 1
+            if mode != "run":
+                profile = args.profile or config.default_profile
+                if profile not in config.profiles:
+                    raise ValueError(f"Unknown endpoint profile: {profile}")
+                if mode == 'conformance':
+                    suite_policy = RunPolicy(timeout_s=args.timeout if args.timeout is not None else 60,
+                        max_tool_rounds=args.max_tool_rounds if args.max_tool_rounds is not None else 2,
+                        max_input_bytes=65536, max_provider_requests=12, max_tool_calls=4,
+                        max_reported_tokens=32768)
+                    report = conformance(config, profile, live=args.live, policy=suite_policy,
+                                         observer=emit if args.events else None)
+                    if args.output == 'text':
+                        print('conformance: ' + report['qualification'])
+                        for case in report['cases']:
+                            print(f"{case['id']}: {case['state']} — {case['reason']}")
+                    else:
+                        emit(report)
+                    return 0 if not args.live or report['qualification'] == 'qualified' else 1
+                if mode == "doctor":
+                    report = doctor(config, profile, inference=args.inference, timeout_s=policy.timeout_s, on_event=sink)
+                else:
+                    report = smoke(config, profile, timeout_s=policy.timeout_s,
+                                   max_tool_rounds=policy.max_tool_rounds, on_event=sink)
+                if args.output == "text":
+                    print(f"{mode}: {'passed' if report['ok'] else 'failed'}")
+                    for name, check in report.get("checks", report.get("tests", {})).items():
+                        print(f"{name}: {check['status']}" + (f" — {check['message']}" if check.get("message") else ""))
+                else:
+                    emit(report)
+                return 0 if report["ok"] else 1
+            recorder = None
+            if args.accounting_dsn_env:
+                if not args.accounting_namespace or not args.accounting_environment:
+                    raise ValueError('accounting requires explicit namespace and environment')
+                dsn = os.environ.get(args.accounting_dsn_env)
+                if not dsn:
+                    raise ValueError('accounting DSN environment variable is not set')
+                try:
+                    from prosaic_runtime_postgres import PostgresRecorder
+                except ImportError as exc:
+                    raise ValueError('install b3-prosaic-runtime-postgres to enable durable accounting') from exc
+                rate_card = None
+                if args.accounting_rate_card:
+                    with open(args.accounting_rate_card, encoding='utf-8') as handle:
+                        rate_card = RateCard(**json.load(handle))
+                recorder = PostgresRecorder(dsn, namespace=args.accounting_namespace,
+                    environment=args.accounting_environment, rate_card=rate_card,
+                    provider_id=args.accounting_provider or 'openai-compatible')
+            elif args.accounting_namespace or args.accounting_environment or args.accounting_rate_card or args.accounting_provider:
+                raise ValueError('accounting options require --accounting-dsn-env')
+            names = ('application_id', 'tenant_id', 'billing_account_id', 'actor_id', 'project_id', 'request_id', 'run_id', 'invocation_id', 'parent_invocation_id')
+            values = {name: getattr(args, name) for name in names if getattr(args, name) is not None}
+            runtime = ProsaicRuntime(config, source=args.source, accounting=recorder)
+            result = runtime.run(args.artifact, args.arguments, cwd=args.cwd, policy=policy, on_event=sink,
+                                 **({'context': ExecutionContext(**values)} if values else {}))
+        if args.output == "text":
+            if result.stdout:
+                print(result.stdout, end="" if result.stdout.endswith("\n") else "\n")
+            if result.exit_code:
+                print(failure_hint(result), file=sys.stderr)
+            return 0 if result.exit_code == 0 else 1
+        if result.exit_code:
+            print(failure_hint(result), file=sys.stderr)
+        emit({"event": "result", **asdict(result)})
+        return 0 if result.exit_code == 0 else 1
+    except KeyboardInterrupt:
+        return 130
+    except (ValueError, TypeError, KeyError, OSError, subprocess.TimeoutExpired) as exc:
+        print(json.dumps({"error": str(exc)}), file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())