activegraph 1.0.1__tar.gz → 1.0.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: activegraph
-Version: 1.0.1
+Version: 1.0.2
 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}/activegraph/__init__.py

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

{activegraph-1.0.1 → activegraph-1.0.2}/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}/activegraph/behaviors/decorators.py

@@ -147,7 +147,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 +177,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:

{activegraph-1.0.1 → activegraph-1.0.2}/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}/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}/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}/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.1 → activegraph-1.0.2}/activegraph/runtime/runtime.py

@@ -376,6 +376,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 +2185,121 @@ _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 validation is permissive: a name no shipped provider recognizes
+    (custom or fine-tuned model) passes silently — only *recognized*
+    cross-provider mismatches fire the diagnostic.
+    """
+    from activegraph.runtime.config_errors import InvalidRuntimeConfiguration
+
+    # 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"
+    provider_recognizes = getattr(provider, "recognizes_model", None)
+    provider_class = type(provider).__name__
+
+    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
+
+        # b.model is an explicit string. Cross-provider validation per
+        # v1.0.2 #1 (b): if the configured provider doesn't recognize the
+        # name, ask each *other* shipped provider class whether it does.
+        # Exactly one other-provider claim ⇒ raise; otherwise pass through.
+        if provider_recognizes is None or provider_recognizes(b.model):
+            continue
+        claimed_by = _which_shipped_provider_claims(b.model, exclude=type(provider))
+        if claimed_by is None:
+            continue
+        # The model name belongs to a different shipped provider's family.
+        # This is the v1.0.1-user-test finding the v1.0.2 patch addresses:
+        # silently sending an Anthropic-family name to OpenAI 404s with no
+        # helpful diagnostic. Fire at registration time, not call time.
+        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={b.name!r}, model={b.model!r}) "
+                f"names a {claimed_by.__name__}-family model, but the "
+                f"runtime is configured with {provider_class}"
+            ),
+            what_failed=(
+                f"The behavior {b.name!r} pinned model={b.model!r}. That "
+                f"name belongs to {claimed_by.__name__}'s model family, "
+                f"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 registration "
+                "time 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": b.name,
+                "model": b.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):
+    """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
+        # Instantiate cheaply: the providers' __init__ doesn't open the SDK.
+        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
+
+
 def _budget_reason(name: Optional[str]) -> str:
     if name is None:
         return "budget.exhausted"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: activegraph
-Version: 1.0.1
+Version: 1.0.2
 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}/activegraph.egg-info/SOURCES.txt

@@ -108,6 +108,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}/pyproject.toml

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