activegraph 1.0.1__tar.gz → 1.0.2.post1__tar.gz

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

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

{activegraph-1.0.1 → activegraph-1.0.2.post1}/activegraph/__init__.py

@@ -221,4 +221,4 @@ __all__ = [
     "tool",
 ]
 
-__version__ = "1.0.1"
+__version__ = "1.0.2.post1"

{activegraph-1.0.1 → activegraph-1.0.2.post1}/activegraph/behaviors/base.py

@@ -93,7 +93,11 @@ class LLMBehavior(Behavior):
 
     handler: Optional[Callable[..., None]] = None
     description: str = ""
-    model: str = "claude-sonnet-4-5"
+    # v1.0.2 #1: model is optional. None = "use the configured provider's
+    # default_model"; the runtime resolves and stamps the concrete string
+    # at registration time. Existing call sites that pass an explicit
+    # string keep working unchanged.
+    model: Optional[str] = None
     output_schema: Optional[type] = None
     deterministic: bool = False
     max_tokens: int = 4096
@@ -134,10 +138,17 @@ class LLMBehavior(Behavior):
             if ar_expr:
                 around_id = _resolve_event_path(ar_expr, event)
             depth = self.view_spec.get("depth")
+        # v1.0.2 #1: if model is still None, the runtime hasn't stamped
+        # a provider default yet — `build_prompt` is for inspection
+        # (CONTRACT v0.6 #20) and must work without a Runtime, so fall
+        # back to the v1.0.1 hardcoded default for inspection-time hash
+        # stability. Real provider calls always go through Runtime,
+        # which resolves the configured provider's default_model first.
+        inspection_model = self.model or "claude-sonnet-4-5"
         return assemble_prompt(
             behavior_name=self.name,
             description=self.description,
-            model=self.model,
+            model=inspection_model,
             output_schema=self.output_schema,
             creates=self.creates,
             view=view,

{activegraph-1.0.1 → activegraph-1.0.2.post1}/activegraph/behaviors/decorators.py

@@ -85,6 +85,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(
@@ -147,7 +153,7 @@ def llm_behavior(
     on: Optional[list[str]] = None,
     where: Optional[dict[str, Any]] = None,
     description: str = "",
-    model: str = "claude-sonnet-4-5",
+    model: Optional[str] = None,
     output_schema: Optional[type] = None,
     view: Optional[dict[str, Any]] = None,
     creates: Optional[list[str]] = None,
@@ -177,6 +183,19 @@ def llm_behavior(
     Keyword-only on purpose — `@llm_behavior` carries enough
     parameters that positional binding would be a footgun.
 
+    ``model=`` is optional (v1.0.2 #1). Omitted, the runtime resolves
+    it to the configured provider's ``default_model`` at registration
+    time — ``"claude-sonnet-4-5"`` for ``AnthropicProvider``,
+    ``"gpt-4o-mini"`` for ``OpenAIProvider``. Passing an explicit
+    model string still works byte-identically; the runtime additionally
+    validates the name against the configured provider's
+    ``recognizes_model()`` and raises
+    :class:`InvalidRuntimeConfiguration` at registration time if the
+    name belongs to a different shipped provider's family (e.g.
+    ``model="gpt-4o-mini"`` on a runtime configured with
+    ``AnthropicProvider``). Names no shipped provider recognizes
+    (custom or fine-tuned models) pass through silently.
+
     `prompt_template=` is the only escape hatch from the
     runtime-assembled prompt. It is a `str.format`-style template that
     receives four placeholders:
@@ -235,6 +254,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.1 → activegraph-1.0.2.post1}/activegraph/llm/anthropic.py

@@ -62,6 +62,10 @@ def _pricing_for(model: str, pricing: Mapping[str, Mapping[str, str]]) -> tuple[
 
 
 class AnthropicProvider(LLMProvider):
+    # v1.0.2 #1: provider-aware default model. @llm_behavior(model=None)
+    # resolves to this string at registration time.
+    default_model: str = "claude-sonnet-4-5"
+
     def __init__(
         self,
         *,
@@ -205,6 +209,10 @@ class AnthropicProvider(LLMProvider):
         result = client.messages.count_tokens(**kwargs)
         return int(getattr(result, "input_tokens", 0) or 0)
 
+    def recognizes_model(self, name: str) -> bool:
+        """True for the ``claude-*`` model family. v1.0.2 #1."""
+        return name.startswith("claude-")
+
 
 # ---- helpers ---------------------------------------------------------------
 

{activegraph-1.0.1 → activegraph-1.0.2.post1}/activegraph/llm/openai.py

@@ -82,6 +82,20 @@ def _pricing_for(
 
 
 class OpenAIProvider(LLMProvider):
+    # v1.0.2 #1: provider-aware default model. @llm_behavior(model=None)
+    # resolves to this string at registration time. gpt-4o-mini is the
+    # cheap, fast member of the GPT-4o family — matches Anthropic's
+    # default-model shape (cheapest sensible default; override for prod).
+    default_model: str = "gpt-4o-mini"
+
+    # v1.0.2 #1: the model-name prefixes this provider recognizes.
+    # `gpt-` covers the GPT-3.5 / GPT-4 / GPT-4o families; the
+    # `o1-` / `o3-` / `o4-` prefixes cover the reasoning-model line
+    # (o1, o3, o4 and their dated variants). Names matching none of
+    # these pass through registration silently per v1.0.2 #1 (b)'s
+    # permissive-default rule.
+    _RECOGNIZED_PREFIXES: tuple[str, ...] = ("gpt-", "o1-", "o3-", "o4-")
+
     def __init__(
         self,
         *,
@@ -267,6 +281,12 @@ class OpenAIProvider(LLMProvider):
             total += 4
         return max(1, total)
 
+    def recognizes_model(self, name: str) -> bool:
+        """True for OpenAI model families (``gpt-*``, ``o1-*``, ``o3-*``,
+        ``o4-*``). v1.0.2 #1.
+        """
+        return any(name.startswith(p) for p in self._RECOGNIZED_PREFIXES)
+
     def _heuristic_count(self, system: str, messages: list[LLMMessage]) -> int:
         if not self._heuristic_warned:
             _log.debug(

{activegraph-1.0.1 → activegraph-1.0.2.post1}/activegraph/llm/provider.py

@@ -1,11 +1,13 @@
 """The `LLMProvider` Protocol every provider implements.
 
-CONTRACT v0.6 #3, extended in v0.7. Narrow, explicit, keyword-only.
-Shipped reference implementation is `AnthropicProvider`. Tests use
+CONTRACT v0.6 #3, extended in v0.7, additively widened in v1.0.2 #1.
+Narrow, explicit, keyword-only. Shipped reference implementations are
+`AnthropicProvider` and `OpenAIProvider`. Tests use
 `RecordedLLMProvider` + `RecordingLLMProvider`. The demo ships its
 own scripted provider.
 
-A provider does three things:
+A provider does three things plus two declarations:
+
   * `complete()`: run a single non-streaming completion. v0.7 adds
     an optional `tools=` parameter; when non-empty, the model is
     allowed to return tool_use blocks in the response.
@@ -14,6 +16,18 @@ A provider does three things:
     prompt that's about to be sent. Used for pre-call budget gating
     when `budget.max_cost_usd` is set; otherwise skipped (see
     CONTRACT v0.6 #4 / decision 10).
+  * `default_model`: the model name to use when an `@llm_behavior`
+    didn't pin one (v1.0.2 #1).
+  * `recognizes_model(name)`: True when `name` belongs to a model
+    family this provider serves. Used by the runtime at
+    registration time to flag cross-provider mismatches before the
+    first network call (v1.0.2 #1).
+
+`default_model` and `recognizes_model` are additive: the runtime
+guards their use with `getattr(...)`, so custom providers that
+pre-date v1.0.2 keep working — they just require an explicit
+`model=` on every `@llm_behavior` and don't participate in
+cross-provider validation.
 
 No streaming, no multi-model orchestration — those are deferred to
 v0.8+. Tool use IS in v0.7, but the loop is orchestrated by the
@@ -32,6 +46,11 @@ from activegraph.llm.types import LLMMessage, LLMResponse
 
 @runtime_checkable
 class LLMProvider(Protocol):
+    # v1.0.2 #1: declared as an attribute on the Protocol. Concrete
+    # providers set it as a class attribute; custom providers may
+    # omit it (the runtime falls back to getattr-with-default).
+    default_model: str
+
     def complete(
         self,
         *,
@@ -64,3 +83,15 @@ class LLMProvider(Protocol):
         model: str,
     ) -> int:
         ...
+
+    def recognizes_model(self, name: str) -> bool:
+        """True when `name` belongs to a model family this provider serves.
+
+        v1.0.2 #1. Used at registration time to flag cross-provider
+        mismatches (e.g. ``model="claude-sonnet-4-5"`` on a runtime
+        configured with ``OpenAIProvider``). Permissive by default:
+        unknown names — fine-tuned models, internal deployment names,
+        experimental prefixes — should return False so the runtime
+        passes them through without a diagnostic.
+        """
+        ...

{activegraph-1.0.1 → activegraph-1.0.2.post1}/activegraph/llm/recorded.py

@@ -110,9 +110,21 @@ class RecordedLLMProvider(LLMProvider):
     silent fallthrough to a real call.
     """
 
+    # v1.0.2 #1: fixtures already carry their own model name in the hash
+    # input, so default-model resolution only matters when an
+    # @llm_behavior omits model=. The recorded provider has no opinion
+    # about which family it's replaying; declare the historical default
+    # so existing fixtures stay reachable.
+    default_model: str = "claude-sonnet-4-5"
+
     def __init__(self, fixtures_dir: str) -> None:
         self._dir = fixtures_dir
 
+    def recognizes_model(self, name: str) -> bool:
+        # Fixture-backed: claim every name so cross-provider validation
+        # doesn't fire against recorded responses.
+        return True
+
     # ---- LLMProvider methods ----
 
     def complete(
@@ -207,6 +219,20 @@ class RecordingLLMProvider(LLMProvider):
         self._dir = fixtures_dir
         os.makedirs(self._dir, exist_ok=True)
 
+    # v1.0.2 #1: delegate default_model + recognizes_model to the inner
+    # provider so wrapping doesn't change the resolution surface. Falls
+    # back to the historical default if the inner provider pre-dates
+    # v1.0.2 and doesn't declare one.
+    @property
+    def default_model(self) -> str:
+        return getattr(self._inner, "default_model", "claude-sonnet-4-5")
+
+    def recognizes_model(self, name: str) -> bool:
+        recognizes = getattr(self._inner, "recognizes_model", None)
+        if recognizes is None:
+            return True
+        return bool(recognizes(name))
+
     def complete(
         self,
         *,

activegraph-1.0.2.post1/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

{activegraph-1.0.1 → activegraph-1.0.2.post1}/activegraph/runtime/runtime.py

@@ -303,6 +303,23 @@ class Runtime:
         self._pack_behaviors: list = []
         self._pack_tools: list = []
 
+        # ---- v1.0.2.post1 #1 (b): eager cross-provider validation ----
+        # First run the bulk validation pass against whatever's already
+        # in the registry; only if it passes do we add this Runtime to
+        # the live-set. Failed constructions stay out of the WeakSet so
+        # they can't influence subsequent register() / @llm_behavior
+        # validation calls. The lazy path inside _ensure_registry()
+        # stays as a defensive double-check.
+        if self.llm_provider is not None:
+            source = (
+                self._explicit_behaviors
+                if self._explicit_behaviors is not None
+                else get_registry()
+            )
+            _resolve_and_validate_llm_models(source, self.llm_provider)
+        from activegraph.runtime._live import track_runtime
+        track_runtime(self)
+
     # ---------- public surface ----------
 
     @property
@@ -376,6 +393,11 @@ class Runtime:
             for b in source:
                 if isinstance(b, LLMBehavior):
                     raise MissingProviderError(behavior_name=b.name)
+        else:
+            # CONTRACT v1.0.2 #1: resolve the provider's default model for
+            # behaviors that didn't pin one, and validate explicit model
+            # names against cross-provider mismatches.
+            _resolve_and_validate_llm_models(source, self.llm_provider)
         self.registry = Registry(source)
 
         # v0.7: assemble the tool registry. Explicit tools= override the
@@ -2180,6 +2202,38 @@ _BUDGET_REASON_MAP = {
 }
 
 
+def _resolve_and_validate_llm_models(source, provider) -> None:
+    """Stamp provider defaults onto LLMBehaviors with model=None, and
+    raise InvalidRuntimeConfiguration for explicit names that belong to
+    a different shipped provider. CONTRACT v1.0.2 #1.
+
+    The cross-provider mismatch check delegates to
+    :func:`activegraph.runtime._live._validate_one` so the same check
+    fires from both binding moments (Runtime construction here,
+    register()/decoration in ``_live.validate_behavior_against_live_runtimes``).
+    """
+    from activegraph.runtime._live import _validate_one
+
+    # Custom providers that pre-date v1.0.2 don't declare `default_model`.
+    # Fall back to the v1.0.1 hardcoded default — keeps every pre-v1.0.2
+    # call site (which silently inherited "claude-sonnet-4-5") working
+    # byte-identically without code changes. The runtime only swaps in a
+    # different default when the provider opts in by declaring one.
+    provider_default = getattr(provider, "default_model", None) or "claude-sonnet-4-5"
+
+    for b in source:
+        if not isinstance(b, LLMBehavior):
+            continue
+        if b.model is None:
+            # v1.0.2 #1 (a): resolve to the provider's default_model
+            # (or the v1.0.1 fallback for custom providers that don't
+            # declare one).
+            b.model = provider_default
+            continue
+        # v1.0.2 #1 (b): cross-provider mismatch check.
+        _validate_one(b, provider)
+
+
 def _budget_reason(name: Optional[str]) -> str:
     if name is None:
         return "budget.exhausted"

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

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

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

@@ -55,6 +55,7 @@ activegraph/packs/diligence/prompts/memo_synthesizer.md
 activegraph/packs/diligence/prompts/question_generator.md
 activegraph/packs/diligence/prompts/risk_identifier.md
 activegraph/runtime/__init__.py
+activegraph/runtime/_live.py
 activegraph/runtime/behavior_graph.py
 activegraph/runtime/budget.py
 activegraph/runtime/config_errors.py
@@ -108,6 +109,7 @@ tests/test_llm_behavior.py
 tests/test_llm_budget.py
 tests/test_llm_causal.py
 tests/test_llm_claim_extraction.py
+tests/test_llm_default_model.py
 tests/test_llm_determinism.py
 tests/test_llm_failure.py
 tests/test_llm_openai.py

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

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