activegraph 1.0.2__tar.gz → 1.0.3__tar.gz

{activegraph-1.0.2 → activegraph-1.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: activegraph
-Version: 1.0.2
+Version: 1.0.3
 Summary: An event-sourced reactive graph runtime for long-running, auditable, agentic systems.
 Author: Active Graph contributors
 License: MIT

{activegraph-1.0.2 → activegraph-1.0.3}/activegraph/__init__.py

@@ -55,7 +55,7 @@ from activegraph.runtime.exec_errors import (
     RuntimeContextRequiredError,
 )
 from activegraph.runtime.patterns import UnsupportedPatternError
-from activegraph.runtime.runtime import Runtime
+from activegraph.runtime.runtime import BehaviorFailure, Runtime
 from activegraph.store import (
     CorruptedEventPayloadError,
     DuplicateEventError,
@@ -125,6 +125,7 @@ __all__ = [
     "AmbiguousToolError",
     "ApprovalNotFoundError",
     "Behavior",
+    "BehaviorFailure",
     "BehaviorNotFoundError",
     "Budget",
     "Clock",
@@ -221,4 +222,4 @@ __all__ = [
     "tool",
 ]
 
-__version__ = "1.0.2"
+__version__ = "1.0.3"

{activegraph-1.0.2 → activegraph-1.0.3}/activegraph/behaviors/decorators.py

@@ -27,6 +27,54 @@ from activegraph.behaviors.base import (
 _REGISTRY: list[Union[Behavior, RelationBehavior]] = []
 
 
+def _validate_output_schema(output_schema: Any) -> None:
+    """Strict-validate ``output_schema=`` at @llm_behavior time.
+
+    CONTRACT v1.0.3 #2. Accepts ``None`` (output_schema is optional)
+    or a Pydantic ``BaseModel`` subclass. Anything else — a dict, a
+    string, an instance instead of a class — raises ``TypeError``
+    with a structured message naming what was passed and showing the
+    correct form as a code example.
+
+    Dict-form output_schema support (JSON-schema dict) is a v1.1
+    candidate per the CONTRACT amendment; the rationale and the
+    fix the user wants live there.
+    """
+    if output_schema is None:
+        return
+    # Import lazily so the framework can still be imported in
+    # environments without Pydantic (e.g., pack metadata tooling).
+    # All real @llm_behavior callsites already require Pydantic
+    # transitively via LLMBehavior.output_schema.
+    try:
+        from pydantic import BaseModel
+    except ImportError:  # pragma: no cover — Pydantic is a hard dep at runtime
+        return
+    if isinstance(output_schema, type) and issubclass(output_schema, BaseModel):
+        return
+    passed = (
+        type(output_schema).__name__
+        if not isinstance(output_schema, type)
+        else f"{output_schema.__name__} (a class, but not a BaseModel subclass)"
+    )
+    raise TypeError(
+        f"output_schema must be a Pydantic BaseModel subclass, not "
+        f"{passed}.\n"
+        f"\n"
+        f"Example:\n"
+        f"    from pydantic import BaseModel\n"
+        f"\n"
+        f"    class MyOutput(BaseModel):\n"
+        f"        result: str\n"
+        f"\n"
+        f"    @llm_behavior(output_schema=MyOutput)\n"
+        f"    def my_behavior(event, graph, ctx, out): ...\n"
+        f"\n"
+        f"Dict-form output_schema (e.g., JSON Schema as a dict) is\n"
+        f"filed as a v1.1 candidate. See CONTRACT v1.0.3 #2."
+    )
+
+
 def clear_registry() -> list[Union[Behavior, RelationBehavior]]:
     """Empty the global behavior registry and return what was cleared.
 
@@ -85,6 +133,12 @@ def register(behavior_obj: Union[Behavior, RelationBehavior]) -> None:
             f"decorators to construct one."
         )
     _REGISTRY.append(behavior_obj)
+    # v1.0.2.post1 #1 (b): if any Runtime is already alive, validate the
+    # new behavior against each one's configured provider so cross-
+    # provider model mismatches fire at the @llm_behavior / register()
+    # line rather than at first run_goal.
+    from activegraph.runtime._live import validate_behavior_against_live_runtimes
+    validate_behavior_against_live_runtimes(behavior_obj)
 
 
 def behavior(
@@ -221,6 +275,12 @@ def llm_behavior(
     if activate_after is not None:
         delay_n = _parse_aa(activate_after)
 
+    # v1.0.3 #2: strict-validate output_schema= at decoration time.
+    # Users who passed a JSON-schema dict previously hit a silent
+    # behavior.failed with reason=llm.schema_violation at first LLM
+    # call; failing here names the cause at the @llm_behavior line.
+    _validate_output_schema(output_schema)
+
     def wrap(fn: Callable) -> LLMBehavior:
         b = LLMBehavior(
             name=name or fn.__name__,
@@ -248,6 +308,12 @@ def llm_behavior(
             max_tool_turns=max_tool_turns,
         )
         _REGISTRY.append(b)
+        # v1.0.2.post1 #1 (b): validate against any live Runtime's
+        # provider. Mirrors the eager check in register() so decorated
+        # behaviors with cross-provider model names fire at the
+        # @llm_behavior line instead of at first run_goal.
+        from activegraph.runtime._live import validate_behavior_against_live_runtimes
+        validate_behavior_against_live_runtimes(b)
         return b
 
     return wrap

{activegraph-1.0.2 → activegraph-1.0.3}/activegraph/core/graph.py

@@ -205,20 +205,40 @@ class Graph:
             [self._relations[i] for i in seen_rels if i in self._relations],
         )
 
-    def query(
+    def objects(
         self,
-        object_type: Optional[str] = None,
+        type: Optional[str] = None,
         where: Optional[dict[str, Any]] = None,
     ) -> list[Object]:
+        """Return objects matching `type` and/or `where`.
+
+        v1.0.3 #1: the canonical query API on `Graph`, mirroring
+        `View.objects(type=...)` so call sites read the same inside
+        and outside behaviors. `Graph.query(object_type=...)` is kept
+        as a backward-compatible alias.
+        """
         out: list[Object] = []
         for o in self._objects.values():
-            if object_type is not None and o.type != object_type:
+            if type is not None and o.type != type:
                 continue
             if where and not _eval_where_on_object(where, o):
                 continue
             out.append(o)
         return out
 
+    def query(
+        self,
+        object_type: Optional[str] = None,
+        where: Optional[dict[str, Any]] = None,
+    ) -> list[Object]:
+        """Backward-compatible alias for :meth:`objects`. v1.0.3 #1.
+
+        New code should use ``graph.objects(type=...)`` — the kwarg
+        ``type`` matches :meth:`View.objects` so the call reads the
+        same in and out of behaviors.
+        """
+        return self.objects(type=object_type, where=where)
+
     def has_object_of_type(self, type_: str) -> bool:
         return any(o.type == type_ for o in self._objects.values())
 

{activegraph-1.0.2 → activegraph-1.0.3}/activegraph/llm/anthropic.py

@@ -257,7 +257,13 @@ def _message_to_anthropic(m: LLMMessage) -> dict[str, Any]:
 
     For role="tool", Anthropic wants a "user" message with a
     `tool_result` content block. For role in {"user","assistant"} the
-    standard {role, content: str} shape works.
+    standard {role, content: str} shape works — except for the
+    multi-turn tool-use case (v1.0.3 #4), where an assistant message
+    that triggered tool_use must echo back its full content blocks
+    (text + tool_use) so the subsequent user tool_result blocks
+    reference matching tool_use_ids in the preceding assistant turn.
+    Direct Anthropic API access tolerated raw_text-only echo; the
+    Vertex AI proxy enforces the spec strictly and 400s without it.
     """
     if m.role == "tool":
         return {
@@ -270,6 +276,20 @@ def _message_to_anthropic(m: LLMMessage) -> dict[str, Any]:
                 }
             ],
         }
+    if m.role == "assistant" and m.tool_calls:
+        blocks: list[dict[str, Any]] = []
+        if m.content:
+            blocks.append({"type": "text", "text": m.content})
+        for tc in m.tool_calls:
+            blocks.append(
+                {
+                    "type": "tool_use",
+                    "id": tc.id,
+                    "name": tc.name,
+                    "input": dict(tc.args),
+                }
+            )
+        return {"role": "assistant", "content": blocks}
     return {"role": m.role, "content": m.content}
 
 

{activegraph-1.0.2 → activegraph-1.0.3}/activegraph/llm/recorded.py

@@ -51,7 +51,7 @@ from typing import Any, Optional
 
 from activegraph.llm.errors import LLMBehaviorError
 from activegraph.llm.provider import LLMProvider
-from activegraph.llm.types import LLMMessage, LLMResponse
+from activegraph.llm.types import LLMMessage, LLMResponse, ToolCall
 
 
 def _now_iso() -> str:
@@ -188,6 +188,21 @@ def _response_from_fixture(
     cost = rdata.get("cost_usd", "0")
     if not isinstance(cost, Decimal):
         cost = Decimal(str(cost))
+    # v1.0.3 #4: reconstruct tool_calls from the fixture so multi-turn
+    # tool-use exchanges replay correctly. Pre-v1.0.3 fixtures and
+    # non-tool-using fixtures have no tool_calls key (or null) and
+    # round-trip to None — backward compatible.
+    tool_calls_raw = rdata.get("tool_calls")
+    tool_calls: Optional[list[ToolCall]] = None
+    if tool_calls_raw:
+        tool_calls = [
+            ToolCall(
+                id=tc.get("id", ""),
+                name=tc.get("name", ""),
+                args=dict(tc.get("args") or {}),
+            )
+            for tc in tool_calls_raw
+        ]
     return LLMResponse(
         raw_text=rdata.get("raw_text", ""),
         parsed=parsed,
@@ -200,6 +215,7 @@ def _response_from_fixture(
         seed=rdata.get("seed"),
         cache_hit=False,
         provider_meta=dict(rdata.get("provider_meta", {}) or {}),
+        tool_calls=tool_calls,
     )
 
 

{activegraph-1.0.2 → activegraph-1.0.3}/activegraph/llm/types.py

@@ -43,12 +43,20 @@ class LLMMessage:
     CONTRACT v0.7: a `role="tool"` message echoes a tool result back to
     the model. `tool_use_id` ties it to the originating tool_use block
     from the previous assistant turn.
+
+    CONTRACT v1.0.3 #4: when an assistant message echoes a turn that
+    triggered tool_use, the originating ToolCall objects travel
+    alongside the raw text via `tool_calls`. The provider adapter
+    reconstructs the wire-format content blocks on the way out. None
+    on every other message shape — single-turn fixtures and zero-tool
+    assistant messages keep their byte-identical serialization.
     """
 
     role: Role
     content: str
     tool_use_id: Optional[str] = None
     tool_name: Optional[str] = None
+    tool_calls: Optional[tuple["ToolCall", ...]] = None
 
     def to_dict(self) -> dict[str, Any]:
         out: dict[str, Any] = {"role": self.role, "content": self.content}
@@ -56,6 +64,10 @@ class LLMMessage:
             out["tool_use_id"] = self.tool_use_id
         if self.tool_name is not None:
             out["tool_name"] = self.tool_name
+        # v1.0.3 #4: only emit `tool_calls` when present so recorded-
+        # fixture hashes for single-turn flows stay byte-identical.
+        if self.tool_calls is not None:
+            out["tool_calls"] = [tc.to_dict() for tc in self.tool_calls]
         return out
 
 

{activegraph-1.0.2 → activegraph-1.0.3}/activegraph/observability/logging.py

@@ -41,6 +41,10 @@ LOG_FIELDS: tuple[str, ...] = (
     "reason",
     "error_type",
     "error_message",
+    # v1.0.3 #3: behavior.failed WARNING log carries the More: URL
+    # for the failure reason's documentation page. Operators tail
+    # logs and click through to the reason's doc-page from the URL.
+    "doc_url",
 )
 
 # Reserved attributes on every LogRecord (stdlib internals). Any

activegraph-1.0.3/activegraph/runtime/_live.py

@@ -0,0 +1,173 @@
+"""Live-Runtime tracking + single-behavior cross-provider validation.
+
+CONTRACT v1.0.2 #1 (b). The validation fires at *both* binding
+moments: ``Runtime(graph, llm_provider=...)`` construction (against
+the existing registry) and ``register()`` / ``@llm_behavior``
+decoration (against any live Runtime via the WeakSet below).
+
+The WeakSet is module-level so the registration decorators can
+look it up without importing ``Runtime`` at module load. Runtimes
+self-register inside ``__init__`` after wiring; the WeakSet
+auto-cleans GC'd Runtimes — no explicit ``Runtime.close()`` is
+required.
+
+The single-behavior validator here is intentionally narrow: it
+only does the cross-provider mismatch check (recognized name
+belonging to a different shipped provider). It does *not* stamp
+provider defaults onto ``model=None`` behaviors — that side
+effect lives in ``_resolve_and_validate_llm_models`` in
+``runtime.py``, which still runs at first ``_ensure_registry``.
+"""
+
+from __future__ import annotations
+
+import weakref
+from typing import TYPE_CHECKING, Any
+
+from activegraph.behaviors.base import LLMBehavior
+
+if TYPE_CHECKING:
+    from activegraph.runtime.runtime import Runtime
+
+
+# WeakSet so abandoned Runtimes don't leak validation calls. The
+# fork/replay paths construct fresh Runtimes that self-register; the
+# parent stays in the set until GC'd.
+_LIVE_RUNTIMES: "weakref.WeakSet[Runtime]" = weakref.WeakSet()
+
+
+def track_runtime(rt: "Runtime") -> None:
+    """Register a live Runtime for cross-provider validation. Called
+    by ``Runtime.__init__`` after the provider and graph are wired."""
+    _LIVE_RUNTIMES.add(rt)
+
+
+def live_runtimes() -> list["Runtime"]:
+    """Snapshot of currently-alive Runtimes (a list of strong refs that
+    the caller releases at end-of-call). Used by ``register()`` and the
+    decorators to validate a new behavior against each live provider."""
+    return list(_LIVE_RUNTIMES)
+
+
+def _clear_for_test() -> None:
+    """Empty the live-Runtime set. Test-only — used by the conftest
+    fixture that isolates the global registry between tests. Production
+    code shouldn't call this: the WeakSet cleans itself on GC."""
+    _LIVE_RUNTIMES.clear()
+
+
+def validate_behavior_against_live_runtimes(behavior: Any) -> None:
+    """Validate a freshly-registered behavior against every live
+    Runtime's provider. Raises :class:`InvalidRuntimeConfiguration` on
+    the first cross-provider mismatch.
+
+    No-op when ``behavior`` isn't an :class:`LLMBehavior`, when no
+    Runtime is live, or when the behavior has no explicit model (model
+    resolution against the provider's default happens at Runtime
+    construction or first-run, not here).
+    """
+    if not isinstance(behavior, LLMBehavior):
+        return
+    if behavior.model is None:
+        return
+    for rt in live_runtimes():
+        provider = getattr(rt, "llm_provider", None)
+        if provider is None:
+            continue
+        _validate_one(behavior, provider)
+
+
+def _validate_one(behavior: LLMBehavior, provider: Any) -> None:
+    """Cross-provider mismatch check for a single behavior against a
+    single provider. Pure: no side effects, no model-default stamping.
+
+    Permissive by default per v1.0.2 #1 (b): names no shipped provider
+    recognizes pass silently. Only recognized cross-provider mismatches
+    raise. The runtime-side ``_resolve_and_validate_llm_models``
+    delegates to this for its per-behavior pass so the check lives in
+    one place.
+    """
+    from activegraph.runtime.config_errors import InvalidRuntimeConfiguration
+
+    model = behavior.model
+    if model is None:
+        return
+    recognizes = getattr(provider, "recognizes_model", None)
+    if recognizes is None or recognizes(model):
+        return
+    claimed_by = _which_shipped_provider_claims(model, exclude=type(provider))
+    if claimed_by is None:
+        return
+
+    provider_class = type(provider).__name__
+    provider_default = getattr(provider, "default_model", None) or "claude-sonnet-4-5"
+    claimed_by_default = getattr(claimed_by, "default_model", "")
+    provider_default_hint = (
+        f"or remove the model= argument to use {provider_class}'s "
+        f"default ({provider_default!r})"
+        if provider_default
+        else f"or set a {provider_class}-compatible model name"
+    )
+    raise InvalidRuntimeConfiguration(
+        (
+            f"@llm_behavior(name={behavior.name!r}, model={model!r}) "
+            f"names a {claimed_by.__name__}-family model, but the "
+            f"runtime is configured with {provider_class}"
+        ),
+        what_failed=(
+            f"The behavior {behavior.name!r} pinned model={model!r}. "
+            f"That name belongs to {claimed_by.__name__}'s model "
+            f"family, but this Runtime was constructed with a "
+            f"{provider_class} instance. Sending the name to the "
+            f"wrong provider produces an HTTP 404 (or equivalent "
+            f"'unknown model' response) at first LLM call, with no "
+            f"hint that the mismatch is the cause."
+        ),
+        why=(
+            "v1.0.2 #1 validates explicit model names at both binding "
+            "moments (Runtime construction and register()/decoration) "
+            "against each shipped provider's recognizes_model() "
+            "method. The configured provider doesn't claim this name, "
+            "but another shipped provider does — that's a "
+            "configuration mismatch worth surfacing before the first "
+            "network call rather than after."
+        ),
+        how_to_fix=(
+            f"Either swap the provider — Runtime(graph, "
+            f"llm_provider={claimed_by.__name__}()) — "
+            f"{provider_default_hint}, or pass an explicit name "
+            f"from {provider_class}'s model families."
+        ),
+        context={
+            "behavior": behavior.name,
+            "model": model,
+            "configured_provider": provider_class,
+            "claimed_by_provider": claimed_by.__name__,
+            "claimed_by_default_model": claimed_by_default,
+        },
+    )
+
+
+def _which_shipped_provider_claims(name: str, *, exclude: type) -> Any:
+    """Return the first shipped provider class that recognizes `name`,
+    excluding `exclude`. Returns None when no other shipped provider
+    claims the name (permissive default per v1.0.2 #1 (b))."""
+    from activegraph.llm.anthropic import AnthropicProvider
+    from activegraph.llm.openai import OpenAIProvider
+
+    candidates = [AnthropicProvider, OpenAIProvider]
+    for cls in candidates:
+        if cls is exclude:
+            continue
+        recognizes = getattr(cls, "recognizes_model", None)
+        if recognizes is None:
+            continue
+        try:
+            inst = cls()
+        except Exception:
+            # Defensive: if a provider's no-arg constructor ever requires
+            # real credentials, skip it for the validation lookup.
+            continue
+        if inst.recognizes_model(name):
+            return cls
+    return None