activegraph 1.0.2.post1__tar.gz → 1.0.4__tar.gz

{activegraph-1.0.2.post1 → activegraph-1.0.4}/PKG-INFO

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

{activegraph-1.0.2.post1 → activegraph-1.0.4}/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.post1"
+__version__ = "1.0.4"

{activegraph-1.0.2.post1 → activegraph-1.0.4}/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.
 
@@ -227,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__,

{activegraph-1.0.2.post1 → activegraph-1.0.4}/activegraph/core/graph.py

@@ -181,6 +181,33 @@ class Graph:
             out.append(r)
         return out
 
+    def relations(
+        self,
+        source: Optional[str] = None,
+        target: Optional[str] = None,
+        type: Optional[str] = None,
+    ) -> list[Relation]:
+        """Return relations filtered by ``source``, ``target``, and/or ``type``.
+
+        v1.0.4 #1: the canonical filter API on ``Graph``. Decomposes the
+        v0 ``get_relations(object_id=, direction=)`` axis into separate
+        ``source`` and ``target`` slots so the call reads the way users
+        already write it (matches ``docs/concepts/graph.md``). Filter
+        kwargs compose by AND; calling with no kwargs returns every
+        relation. ``Graph.get_relations(object_id=, type=, direction=)``
+        stays as a backward-compatible alias.
+        """
+        out: list[Relation] = []
+        for r in self._relations.values():
+            if source is not None and r.source != source:
+                continue
+            if target is not None and r.target != target:
+                continue
+            if type is not None and r.type != type:
+                continue
+            out.append(r)
+        return out
+
     def neighborhood(self, object_id: str, depth: int = 1) -> tuple[list[Object], list[Relation]]:
         if object_id not in self._objects:
             return ([], [])
@@ -205,20 +232,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.post1 → activegraph-1.0.4}/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.post1 → activegraph-1.0.4}/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.post1 → activegraph-1.0.4}/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.post1 → activegraph-1.0.4}/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.2.post1 → activegraph-1.0.4}/activegraph/runtime/runtime.py

@@ -65,7 +65,7 @@ def _monotonic() -> float:
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from decimal import Decimal
-from typing import Any, Callable, Iterable, Optional, Union
+from typing import Any, Callable, Iterable, NamedTuple, Optional, Union
 
 from activegraph.behaviors.base import Behavior, LLMBehavior, RelationBehavior
 from activegraph.behaviors.decorators import get_registry
@@ -170,6 +170,58 @@ class Context:
         )
 
 
+class BehaviorFailure(NamedTuple):
+    """Structured view of a ``behavior.failed`` event for
+    :attr:`Runtime.errors`. CONTRACT v1.0.3 #3.
+
+    Five fields capture the operationally important parts of a
+    failure: which behavior, which event triggered it, the v0.6 #11
+    reason code (when present), the Python exception class name, and
+    the exception message. ``failed_event_id`` ties the structured
+    view back to the underlying ``behavior.failed`` event so callers
+    that want the full payload (traceback, payload extras) can
+    re-read it from ``runtime.graph._events``.
+
+    Not exposed as a class users construct — it's a projection of
+    the events the runtime emits, and the runtime is the only writer.
+    Distinct from Python's builtin ``RuntimeError``; named
+    ``BehaviorFailure`` to avoid the shadow.
+    """
+
+    behavior: str
+    event_id: str
+    reason: Optional[str]
+    exception_type: str
+    message: str
+    failed_event_id: str
+
+
+# Map v0.6 #11 reason-code prefixes to the framework error class's
+# doc-page slug. Used by the WARNING log emitted from
+# `_emit_behavior_failed` so the log line carries a More: URL the
+# operator can open. The slugs are class-level (the v1.0 #4 More:
+# URL convention) — a per-reason slug doesn't exist today.
+_REASON_PREFIX_TO_DOC_SLUG: tuple[tuple[str, str], ...] = (
+    ("llm.", "llm-behavior-error"),
+    ("tool.", "tool-error"),
+    ("budget.", "budget-exhausted"),
+)
+
+
+def _doc_url_for_reason(reason: str) -> str:
+    """Return the More: doc-page URL for a v0.6 #11 reason code.
+
+    Defaults to the generic execution-error page when no prefix
+    matches (covers ``exception.*`` reasons from generic catches).
+    """
+    from activegraph.errors import DOCS_BASE_URL
+
+    for prefix, slug in _REASON_PREFIX_TO_DOC_SLUG:
+        if reason.startswith(prefix):
+            return f"{DOCS_BASE_URL}/errors/{slug}"
+    return f"{DOCS_BASE_URL}/errors/execution-error"
+
+
 class Runtime:
     def __init__(
         self,
@@ -326,6 +378,38 @@ class Runtime:
     def run_id(self) -> str:
         return self.graph.run_id
 
+    @property
+    def errors(self) -> list[BehaviorFailure]:
+        """Accumulated ``behavior.failed`` events as structured tuples.
+
+        v1.0.3 #3. Reads from ``self.graph._events`` on each access —
+        the events are the source of truth and this property is a
+        projection. No caching, no listener registration, no new
+        state. Callers can inspect failures programmatically without
+        reaching into ``graph._events`` or parsing payload dicts.
+
+        Each :class:`BehaviorFailure` carries five operationally
+        useful fields plus the underlying ``behavior.failed`` event
+        id for callers that want to re-read the full payload (e.g.,
+        traceback, LLM payload extras).
+        """
+        out: list[BehaviorFailure] = []
+        for e in self.graph._events:
+            if e.type != "behavior.failed":
+                continue
+            p = e.payload
+            out.append(
+                BehaviorFailure(
+                    behavior=p.get("behavior", ""),
+                    event_id=p.get("event_id", ""),
+                    reason=p.get("reason"),
+                    exception_type=p.get("exception_type", ""),
+                    message=p.get("message", ""),
+                    failed_event_id=e.id,
+                )
+            )
+        return out
+
     # ---------- listener ----------
 
     def _on_event(self, event: Event) -> None:
@@ -661,27 +745,12 @@ class Runtime:
                 "activegraph_behaviors_failed_total",
                 {"behavior": b.name, "reason": f"exception.{type(e).__name__}"},
             )
-            self._log.error(
-                "behavior failed",
-                extra=runtime_log_extra(
-                    run_id=self.graph.run_id,
-                    event_id=event.id,
-                    behavior=b.name,
-                    reason=f"exception.{type(e).__name__}",
-                    error_type=type(e).__name__,
-                    error_message=str(e),
-                ),
-            )
-            self._emit_lifecycle(
-                "behavior.failed",
-                {
-                    "behavior": b.name,
-                    "event_id": event.id,
-                    "exception_type": type(e).__name__,
-                    "message": str(e),
-                    "traceback": traceback.format_exc(),
-                },
-            )
+            # v1.0.3 #3: route through _emit_behavior_failed so the
+            # WARNING log line and the event emission stay in one
+            # place. The previous ERROR log is removed — the
+            # centralized emitter handles logging at WARNING for
+            # every behavior.failed.
+            self._emit_behavior_failed(b.name, event.id, e)
             return
 
         self.metrics.histogram(
@@ -974,14 +1043,22 @@ class Runtime:
                 break
 
             # Tool calls. Append the assistant turn to messages, then
-            # dispatch each tool. Anthropic's assistant turn that
-            # triggers tool_use carries the model's reasoning text plus
-            # the tool_use blocks; we approximate by including raw_text
-            # (may be empty) — the providers' adapters handle the rest.
-            if turn_response.raw_text:
-                running_messages.append(
-                    LLMMessage(role="assistant", content=turn_response.raw_text)
+            # dispatch each tool. v1.0.3 #4: the assistant turn must
+            # carry both the text and the tool_use blocks. Anthropic
+            # requires every following tool_result block to reference
+            # a tool_use_id from the preceding assistant message; the
+            # Vertex AI proxy enforces this strictly (HTTP 400 without
+            # matching blocks), and the direct API tolerates the raw-
+            # text-only form for now but is expected to tighten. The
+            # provider adapter reconstructs the wire-format content
+            # blocks from `tool_calls`.
+            running_messages.append(
+                LLMMessage(
+                    role="assistant",
+                    content=turn_response.raw_text or "",
+                    tool_calls=tuple(response_tool_calls),
                 )
+            )
             for call in response_tool_calls:
                 # CONTRACT v0.7 #6: budget enforcement BEFORE invocation
                 # so an exhausted budget fails the behavior, doesn't
@@ -1411,6 +1488,14 @@ class Runtime:
     ) -> None:
         """Centralized behavior.failed emission. CONTRACT #13 plus
         v0.6 #11 (optional `reason` + LLM-specific extras).
+
+        v1.0.3 #3: emits a WARNING log line so callers running
+        ``runtime.run_goal()`` see failures without subscribing to
+        ``behavior.failed`` or inspecting ``graph._events``. Users
+        opt out via standard ``logging.getLogger('activegraph.runtime')``
+        configuration. Every ``behavior.failed`` emission routes
+        through this method so exactly one log line is produced per
+        failure at one consistent level.
         """
 
         tb_str = "".join(
@@ -1429,6 +1514,24 @@ class Runtime:
             for k, v in extras.items():
                 if k not in payload:
                     payload[k] = v
+        # v1.0.3 #3: WARNING log with doc_url pointing at the reason's
+        # documentation page. Slug is class-level (the v1.0 #4 More:
+        # URL convention) — LLMBehaviorError for llm.*, ToolError for
+        # tool.*, ConfigurationError for budget.*, else the generic
+        # execution-error page.
+        log_reason = reason or f"exception.{type(exc).__name__}"
+        self._log.warning(
+            f"behavior failed: {behavior_name} (reason={log_reason})",
+            extra=runtime_log_extra(
+                run_id=self.graph.run_id,
+                event_id=event_id,
+                behavior=behavior_name,
+                reason=log_reason,
+                error_type=type(exc).__name__,
+                error_message=str(exc),
+                doc_url=_doc_url_for_reason(log_reason),
+            ),
+        )
         self._emit_lifecycle("behavior.failed", payload)
 
     def _invoke_relation(
@@ -1470,16 +1573,10 @@ class Runtime:
         try:
             b.run(relation, event, bgraph, ctx)
         except Exception as e:
-            self._emit_lifecycle(
-                "behavior.failed",
-                {
-                    "behavior": b.name,
-                    "event_id": event.id,
-                    "exception_type": type(e).__name__,
-                    "message": str(e),
-                    "traceback": traceback.format_exc(),
-                },
-            )
+            # v1.0.3 #3: route through _emit_behavior_failed so
+            # relation-behavior failures go through the same WARNING
+            # log + event emission path as function and LLM behaviors.
+            self._emit_behavior_failed(b.name, event.id, e)
             return
 
         self._emit_lifecycle(

{activegraph-1.0.2.post1 → activegraph-1.0.4}/activegraph/tools/graph_query.py

@@ -68,7 +68,7 @@ def make_graph_query_tool(graph) -> Tool:
     """
 
     def fn(args: GraphQueryInput, ctx: ToolContext) -> GraphQueryOutput:
-        results = graph.query(object_type=args.object_type, where=args.where)
+        results = graph.objects(type=args.object_type, where=args.where)
         truncated = len(results) > args.limit
         results = results[: args.limit]
         return GraphQueryOutput(

{activegraph-1.0.2.post1 → activegraph-1.0.4}/activegraph.egg-info/PKG-INFO

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

{activegraph-1.0.2.post1 → activegraph-1.0.4}/activegraph.egg-info/SOURCES.txt

@@ -149,6 +149,8 @@ tests/test_tools.py
 tests/test_trace.py
 tests/test_tutorial_snippets.py
 tests/test_v1_0_1_patches.py
+tests/test_v1_0_3_behavior_failed_ux.py
+tests/test_v1_0_3_tool_multiturn.py
 tests/test_version_sync.py
 tests/test_view.py
 tests/test_wheel_completeness.py

{activegraph-1.0.2.post1 → activegraph-1.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "activegraph"
-version = "1.0.2.post1"
+version = "1.0.4"
 description = "An event-sourced reactive graph runtime for long-running, auditable, agentic systems."
 readme = "README.md"
 requires-python = ">=3.11"