power-loop 9.0.0__tar.gz → 10.0.0__tar.gz

{power_loop-9.0.0 → power_loop-10.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: power-loop
-Version: 9.0.0
+Version: 10.0.0
 Summary: Embeddable agent execution kernel — LLM loop, hooks, events, tools, dynamic sub-agents.
 Author-email: zhangran <zhangran24@126.com>
 License: MIT
@@ -418,3 +418,62 @@ After the exact charge is locally durable, API delivery failure leaves a pending
 budget submission and preserves the real tool result. Reconciliation never calls
 the handler again or reads a replacement price. Managed recovery sources without
 an ordinary callback checkpoint still need a separate adapter.
+
+
+### Host lifecycle extensions
+
+Hosts can raise `power_loop.core.control.ControlledLoopStop(reason, message=...)`
+from session-entry or round-start hooks. The pipeline records a controlled stop,
+keeps completed work, and skips memory summarization on that exit. Hosts own
+quota policy and settlement; the SDK has no application currency or user model.
+
+`power_loop.runtime.invocation.register_invocation_scope(name, factory, exporter=...)`
+installs a synchronous context manager around each actual tool invocation. The
+factory receives `session_id`, `assistant_seq`, `tool_call_id`, and `tool_name`.
+An optional exporter returns a small JSON snapshot which is saved as
+`host_contexts[name]` on original job creation. Replay retains the original saved
+snapshot; hosts restore it when recovering a child job. Business snapshots do not
+carry execution authority and do not replace the SDK's signed task request.
+# Response usage and supplier cost (10.0)
+
+`LLMResponse.token_usage` contains standardized token counts.
+`LLMResponse.provider_cost` is an independent `ProviderCost(amount, currency)`;
+`amount` is an exact decimal string and `None` means the supplier did not report
+money. Explicit zero is a valid supplier invoice. `LLMTokenUsage.cost` is removed.
+
+`TokenUsageExtractor` and `CostExtractor` have default implementations. OpenAI,
+Anthropic and Gemini usage shapes are recognized through the same interfaces.
+Override nested paths per connection with `LLMProviderConfig.response_extraction`:
+
+```python
+config.response_extraction = {
+    "usage": {
+        "paths": {
+            "prompt_tokens": "data.usage.input",
+            "completion_tokens": "data.usage.output",
+            "prompt_cached_tokens": "data.usage.cache",
+        },
+        "on_error": "raise",
+    },
+    "cost": {
+        "amount_path": "data.billing.amount",
+        "currency_path": "data.billing.currency",
+        "currency": "USD",  # explicit default when no currency field is present
+        "on_error": "raise",
+    },
+}
+```
+
+Blank mappings use defaults. Missing fields/container mismatches are normal
+misses. Invalid values produce structured diagnostics. `on_error="continue"`
+returns unknown supplier money, never an invented zero. The agent loop enforces
+the default raise policy after retaining original response evidence and outside
+the transport retry loop. A host can then price complete token usage, or retain
+unknown financial responsibility when neither reliable cost nor usage is known.
+
+`ResponseMetrics(config).inspect(raw_json)` validates offline with no model
+request; `extract_usage` and `extract_cost` also accept custom implementations.
+Trusted hosts may supply `usage.code` / `cost.code` snippets declaring
+`extract(response)`. This is an internal extension, not a public code editor or
+an untrusted-code execution service. Its standardized output and error policies
+are identical to field mappings.

{power_loop-9.0.0 → power_loop-10.0.0}/README.md

@@ -340,3 +340,62 @@ After the exact charge is locally durable, API delivery failure leaves a pending
 budget submission and preserves the real tool result. Reconciliation never calls
 the handler again or reads a replacement price. Managed recovery sources without
 an ordinary callback checkpoint still need a separate adapter.
+
+
+### Host lifecycle extensions
+
+Hosts can raise `power_loop.core.control.ControlledLoopStop(reason, message=...)`
+from session-entry or round-start hooks. The pipeline records a controlled stop,
+keeps completed work, and skips memory summarization on that exit. Hosts own
+quota policy and settlement; the SDK has no application currency or user model.
+
+`power_loop.runtime.invocation.register_invocation_scope(name, factory, exporter=...)`
+installs a synchronous context manager around each actual tool invocation. The
+factory receives `session_id`, `assistant_seq`, `tool_call_id`, and `tool_name`.
+An optional exporter returns a small JSON snapshot which is saved as
+`host_contexts[name]` on original job creation. Replay retains the original saved
+snapshot; hosts restore it when recovering a child job. Business snapshots do not
+carry execution authority and do not replace the SDK's signed task request.
+# Response usage and supplier cost (10.0)
+
+`LLMResponse.token_usage` contains standardized token counts.
+`LLMResponse.provider_cost` is an independent `ProviderCost(amount, currency)`;
+`amount` is an exact decimal string and `None` means the supplier did not report
+money. Explicit zero is a valid supplier invoice. `LLMTokenUsage.cost` is removed.
+
+`TokenUsageExtractor` and `CostExtractor` have default implementations. OpenAI,
+Anthropic and Gemini usage shapes are recognized through the same interfaces.
+Override nested paths per connection with `LLMProviderConfig.response_extraction`:
+
+```python
+config.response_extraction = {
+    "usage": {
+        "paths": {
+            "prompt_tokens": "data.usage.input",
+            "completion_tokens": "data.usage.output",
+            "prompt_cached_tokens": "data.usage.cache",
+        },
+        "on_error": "raise",
+    },
+    "cost": {
+        "amount_path": "data.billing.amount",
+        "currency_path": "data.billing.currency",
+        "currency": "USD",  # explicit default when no currency field is present
+        "on_error": "raise",
+    },
+}
+```
+
+Blank mappings use defaults. Missing fields/container mismatches are normal
+misses. Invalid values produce structured diagnostics. `on_error="continue"`
+returns unknown supplier money, never an invented zero. The agent loop enforces
+the default raise policy after retaining original response evidence and outside
+the transport retry loop. A host can then price complete token usage, or retain
+unknown financial responsibility when neither reliable cost nor usage is known.
+
+`ResponseMetrics(config).inspect(raw_json)` validates offline with no model
+request; `extract_usage` and `extract_cost` also accept custom implementations.
+Trusted hosts may supply `usage.code` / `cost.code` snippets declaring
+`extract(response)`. This is an internal extension, not a public code editor or
+an untrusted-code execution service. Its standardized output and error policies
+are identical to field mappings.

{power_loop-9.0.0 → power_loop-10.0.0}/power_loop/__init__.py

@@ -15,7 +15,7 @@ Stability tiers
 无版本承诺，可随时变更或删除。
 """
 
-__version__ = "9.0.0"
+__version__ = "10.0.0"
 
 # Public LLM contract (SDK-free) re-exported so callers (e.g. writing llm.* hooks or
 # a custom LLMService) don't reach into the internal vendored transport package (H3.4).
@@ -265,6 +265,18 @@ from power_loop.tools.spawn_agent import (
     register_spawn_agent,
 )
 
+from .llm_metrics import (
+    CostExtractor,
+    DefaultCostExtractor,
+    DefaultTokenUsageExtractor,
+    FieldCostExtractor,
+    FieldTokenUsageExtractor,
+    ProviderCost,
+    ResponseExtractionError,
+    ResponseMetrics,
+    TokenUsageExtractor,
+)
+
 _logging.getLogger("power_loop").addHandler(_logging.NullHandler())
 
 
@@ -306,9 +318,27 @@ STABLE_API = (
     "ModelCapabilityError",
     "create_llm_service_from_env",
     "create_llm_service_from_config",
+    "ResponseMetrics",
+    "ProviderCost",
+    "TokenUsageExtractor",
+    "CostExtractor",
+    "DefaultTokenUsageExtractor",
+    "DefaultCostExtractor",
+    "FieldTokenUsageExtractor",
+    "FieldCostExtractor",
+    "ResponseExtractionError",
 )
 
 __all__ = [
+    "ResponseMetrics",
+    "ProviderCost",
+    "TokenUsageExtractor",
+    "CostExtractor",
+    "DefaultTokenUsageExtractor",
+    "DefaultCostExtractor",
+    "FieldTokenUsageExtractor",
+    "FieldCostExtractor",
+    "ResponseExtractionError",
     "PASS_TURN_TOOL",
     "request_pass",
     "pass_progress",

{power_loop-9.0.0 → power_loop-10.0.0}/power_loop/_vendor/llm_client/anthropic_factory.py

@@ -10,7 +10,8 @@ from typing import Any
 from anthropic import AsyncAnthropic, DefaultAsyncHttpxClient
 
 from .capabilities import ModelCapabilities, coerce_capabilities
-from .interface import AnthropicChatConfig, LLMRequest, LLMResponse, LLMService, LLMStreamChunk, LLMTokenUsage
+from .exact_json import configure_http_client
+from .interface import AnthropicChatConfig, LLMRequest, LLMResponse, LLMService, LLMStreamChunk
 from .llm_utils import parse_json_from_model_output_detailed
 from .multimodal import render_message_content
 from .proxy_fallback import env_proxy_http_client
@@ -77,7 +78,7 @@ class AnthropicMessagesLLMService(LLMService):
                 base_url=self._cfg.base_url,
                 timeout=self._cfg.timeout_s,
                 max_retries=self._cfg.max_retries,
-                http_client=env_proxy_http_client(DefaultAsyncHttpxClient),
+                http_client=configure_http_client(env_proxy_http_client(DefaultAsyncHttpxClient) or DefaultAsyncHttpxClient()),
             )
         return self._client.with_options(max_retries=0) if single_attempt.get() else self._client
 
@@ -89,39 +90,15 @@ class AnthropicMessagesLLMService(LLMService):
         finally:
             self._client = None
 
-    def _usage_dict_from_any(self, usage: Any) -> dict[str, Any]:
-        raw = _as_dict(usage)
+    def _usage_dict_from_any(self, usage: Any = None):
+        from power_loop.llm_metrics import DefaultTokenUsageExtractor
+        result = DefaultTokenUsageExtractor().extract({"usage": self._last_usage if usage is None else usage})
+        return result.as_dict() if result is not None else {}
 
-        def _int_or_none(value: Any) -> int | None:
-            try:
-                return None if value is None else int(value)
-            except Exception:
-                return None
-
-        prompt = _int_or_none(raw.get("input_tokens") or raw.get("prompt_tokens"))
-        completion = _int_or_none(raw.get("output_tokens") or raw.get("completion_tokens"))
-        total = _int_or_none(raw.get("total_tokens"))
-        if total is None and prompt is not None and completion is not None:
-            total = prompt + completion
-        raw["prompt_tokens"] = prompt
-        raw["completion_tokens"] = completion
-        raw["total_tokens"] = total
-        return raw
-
-    def _usage_obj(self, usage: Any = None) -> LLMTokenUsage:
-        d = self._last_usage if usage is None else self._usage_dict_from_any(usage)
-
-        def _int_or_none(value: Any) -> int | None:
-            try:
-                return None if value is None else int(value)
-            except Exception:
-                return None
-
-        return LLMTokenUsage(
-            prompt_tokens=_int_or_none(d.get("prompt_tokens")),
-            completion_tokens=_int_or_none(d.get("completion_tokens")),
-            total_tokens=_int_or_none(d.get("total_tokens")),
-        )
+    def _usage_obj(self, usage: Any = None):
+        from power_loop.llm_metrics import DefaultTokenUsageExtractor
+        result = DefaultTokenUsageExtractor().extract({"usage": self._last_usage if usage is None else usage})
+        return result
 
     def _record_usage(self, usage: Any) -> None:
         self._last_usage = self._usage_dict_from_any(usage)
@@ -407,6 +384,8 @@ class AnthropicMessagesLLMService(LLMService):
             maybe = on_stream_end(result)
             if hasattr(maybe, "__await__"):
                 await maybe
+        from power_loop.llm_metrics import ResponseMetrics
+        ResponseMetrics(self._cfg.response_extraction).apply(result)
         return result
 
     async def stream(self, request: LLMRequest) -> AsyncIterator[LLMStreamChunk]:

power_loop-10.0.0/power_loop/_vendor/llm_client/exact_json.py

@@ -0,0 +1,28 @@
+"""Retain JSON decimal literals before provider SDKs normalize their objects."""
+import json
+from decimal import Decimal
+
+
+def exact_event(event):
+    event.json = lambda: json.loads(event.data, parse_float=Decimal)
+    return event
+
+
+async def exact_response_json(response):
+    if getattr(response, '_power_loop_exact_json', False):
+        return
+    original = response.json
+
+    def parse(**options):
+        options.setdefault('parse_float', Decimal)
+        return original(**options)
+
+    response.json = parse
+    response._power_loop_exact_json = True
+
+
+def configure_http_client(client):
+    hooks = client.event_hooks.setdefault('response', [])
+    if exact_response_json not in hooks:
+        hooks.append(exact_response_json)
+    return client

{power_loop-9.0.0 → power_loop-10.0.0}/power_loop/_vendor/llm_client/interface.py

@@ -204,10 +204,6 @@ class LLMTokenUsage:
     accepted_tokens: int | None = None
     rejected_tokens: int | None = None
 
-    #: Charge the provider itself reported for this call (e.g. OpenRouter's ``usage.cost``), in the
-    #: provider's billing currency. ``None`` = not reported; hosts then price tokens themselves.
-    cost: float | None = None
-
     def as_dict(self) -> dict[str, int | None]:
         return dict(self.__dict__)
 
@@ -242,6 +238,8 @@ class LLMStreamChunk:
     token_usage: LLMTokenUsage | None = None
     raw_event: Any = None
     is_final: bool = False
+    provider_cost: Any = None
+    response_metrics: dict[str, Any] = field(default_factory=dict)
 
 
 @dataclass
@@ -274,6 +272,7 @@ class LLMResponse:
     tool_calls: list[dict[str, Any]] = field(default_factory=list)
     # Raw streamed chunks captured when complete() is implemented via stream aggregation.
     stream_chunks: list[LLMStreamChunk] = field(default_factory=list)
+    provider_cost: Any = None
 
     def get_tool_calls(self) -> list[dict[str, Any]]:
         """
@@ -537,6 +536,7 @@ class OpenAICompatibleChatConfig:
     # (e.g. DashScope ``extra_body.enable_thinking``) on for a whole loop without touching the
     # pipeline's per-call LLMRequest.
     request_extra: dict[str, Any] = field(default_factory=dict)
+    response_extraction: dict[str, Any] = field(default_factory=dict)
 
     @property
     def is_ready(self) -> bool:
@@ -556,6 +556,7 @@ class AnthropicChatConfig:
     #: transport used to carry none at all, which is how ``attachment`` blocks reached it
     #: unrendered and got dropped as "unsupported content block".
     capabilities: dict[str, Any] = field(default_factory=dict)
+    response_extraction: dict[str, Any] = field(default_factory=dict)
 
     @property
     def is_ready(self) -> bool: