activegraph 1.0.0rc2__tar.gz → 1.0.1__tar.gz

{activegraph-1.0.0rc2 → activegraph-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: activegraph
-Version: 1.0.0rc2
+Version: 1.0.1
 Summary: An event-sourced reactive graph runtime for long-running, auditable, agentic systems.
 Author: Active Graph contributors
 License: MIT
@@ -18,7 +18,16 @@ Requires-Dist: click<9,>=8
 Requires-Dist: pydantic>=2
 Provides-Extra: llm
 Requires-Dist: anthropic>=0.40; extra == "llm"
+Requires-Dist: openai>=1.0; extra == "llm"
+Requires-Dist: tiktoken>=0.7; extra == "llm"
 Requires-Dist: pydantic>=2; extra == "llm"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40; extra == "anthropic"
+Requires-Dist: pydantic>=2; extra == "anthropic"
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"
+Requires-Dist: tiktoken>=0.7; extra == "openai"
+Requires-Dist: pydantic>=2; extra == "openai"
 Provides-Extra: sqlite
 Provides-Extra: postgres
 Requires-Dist: psycopg[binary]<4,>=3.1; extra == "postgres"
@@ -26,6 +35,8 @@ Provides-Extra: prometheus
 Requires-Dist: prometheus_client>=0.20; extra == "prometheus"
 Provides-Extra: all
 Requires-Dist: anthropic>=0.40; extra == "all"
+Requires-Dist: openai>=1.0; extra == "all"
+Requires-Dist: tiktoken>=0.7; extra == "all"
 Requires-Dist: pydantic>=2; extra == "all"
 Requires-Dist: psycopg[binary]<4,>=3.1; extra == "all"
 Requires-Dist: prometheus_client>=0.20; extra == "all"
@@ -34,6 +45,10 @@ Requires-Dist: pytest>=7; extra == "dev"
 Requires-Dist: pydantic>=2; extra == "dev"
 Requires-Dist: prometheus_client>=0.20; extra == "dev"
 Requires-Dist: psycopg[binary]<4,>=3.1; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
 
 # Active Graph
 
@@ -73,12 +88,20 @@ capability.
 
 ```bash
 pip install activegraph                    # core runtime + SQLite store + Diligence pack
-pip install "activegraph[llm]"             # Anthropic provider
+pip install "activegraph[llm]"             # Anthropic + OpenAI providers
+pip install "activegraph[anthropic]"       # Anthropic provider only
+pip install "activegraph[openai]"          # OpenAI provider only (+ tiktoken)
 pip install "activegraph[postgres]"        # Postgres-backed event store
 pip install "activegraph[prometheus]"      # Prometheus metrics
 pip install "activegraph[all]"             # everything
 ```
 
+Both LLM providers expose the same `LLMProvider` Protocol surface;
+swap one for the other without touching `@llm_behavior` definitions.
+The [LLM providers reference](https://docs.activegraph.ai/reference/llm-providers/)
+covers the side-by-side surface and the v1.0.1 limitations
+(OpenAI tool use is a v1.1 candidate).
+
 Python 3.11+. Two hard dependencies (`click` for the CLI, `pydantic`
 for the pack format); persistence backends and provider integrations
 are opt-in extras.
@@ -102,7 +125,54 @@ are opt-in extras.
   8 object types, 7 behaviors, 3 tools, recorded fixtures.
 - **Per-error reference pages.** Every error message ends with a
   `More:` link to a page that explains when it fires, why, and how to
-  fix it. Catalog at [docs.activegraph.dev/reference/errors](https://docs.activegraph.dev/reference/errors/).
+  fix it. Catalog at [docs.activegraph.ai/reference/errors](https://docs.activegraph.ai/reference/errors/).
+
+## Concepts at a glance
+
+The framework's twelve primitives, in roughly the order you meet them
+when reading a trace. Each links to its concept page on the doc site;
+read those when you want depth on one piece.
+
+- **Graph** — objects and typed relations forming the world the
+  framework reasons about. The graph is a projection of the event log;
+  every mutation is an event. [→ concepts/graph](https://docs.activegraph.ai/concepts/graph/)
+- **Events** — the append-only history. Every behavior fires in
+  response to events and produces more events; the trace is the
+  ordered log of all of them. [→ concepts/events](https://docs.activegraph.ai/concepts/events/)
+- **Behaviors** — the unit of reactive code. Function, class, or
+  LLM-backed; declares what events it subscribes to and what it
+  produces. The determinism contract is per-behavior. [→ concepts/behaviors](https://docs.activegraph.ai/concepts/behaviors/)
+- **Relations** — typed edges between objects, with their own
+  behaviors. The relation-behavior primitive — coordination logic on
+  the edge, not on either endpoint — is uncommon in other agent
+  frameworks. [→ concepts/relations](https://docs.activegraph.ai/concepts/relations/)
+- **Patches** — proposed mutations with optimistic concurrency.
+  Behaviors propose patches; the runtime applies or rejects them;
+  rejections are events in their own right. [→ concepts/patches](https://docs.activegraph.ai/concepts/patches/)
+- **Views** — scoped reads of the graph for behavior context. Type
+  filters, depth filters, recent-event windows. Views are how
+  pattern-driven behaviors see only what they need to. [→ concepts/views](https://docs.activegraph.ai/concepts/views/)
+- **Frames** — bounded contexts for a run. Goal, constraints, budget,
+  and the registered behaviors for this frame. A run can have one
+  frame or many. [→ concepts/frames](https://docs.activegraph.ai/concepts/frames/)
+- **Policies** — approval and gating for behavior capabilities. Which
+  behaviors can call which tools, which mutations require human
+  approval, what the runtime refuses. [→ concepts/policies](https://docs.activegraph.ai/concepts/policies/)
+- **Patterns** — the Cypher subset for pattern subscriptions. Beyond
+  event-type + predicate, behaviors can subscribe to graph shapes
+  (claim-cited-by-evidence, task-blocks-task, …) with `NOT EXISTS`
+  and temporal predicates. [→ concepts/patterns](https://docs.activegraph.ai/concepts/patterns/)
+- **Replay** — re-execute a run from its event log. Strict mode
+  re-fires every behavior and fails on divergence; permissive mode
+  reconstructs state without re-firing. The LLM replay cache is what
+  makes fork cheap. [→ concepts/replay](https://docs.activegraph.ai/concepts/replay/)
+- **Forking** — branch any run at any event into an independent
+  fork; structurally diff the fork against the parent. The framework's
+  mechanism for hypothesis testing on agentic systems. [→ concepts/forking](https://docs.activegraph.ai/concepts/forking/)
+- **Failure model** — a behavior failure is a `behavior.failed`
+  event, not an exception. The audit trail captures failures as
+  first-class history. Exceptions live at runtime entry points only.
+  [→ concepts/failure-model](https://docs.activegraph.ai/concepts/failure-model/)
 
 ## A small example
 
@@ -140,14 +210,14 @@ runtime.print_trace()
 
 The `unblock` relation behavior fires only for events touching one of
 its edge endpoints. The conceptual deep-dive on edges-with-logic is
-in [`docs/concepts/relations.md`](https://docs.activegraph.dev/concepts/relations/).
+in [`docs/concepts/relations.md`](https://docs.activegraph.ai/concepts/relations/).
 
 ## Documentation
 
-- **[docs.activegraph.dev](https://docs.activegraph.dev/)** — full doc site:
+- **[docs.activegraph.ai](https://docs.activegraph.ai/)** — full doc site:
   concepts, guides, cookbook, CLI reference, API reference, the
   per-error catalog.
-- **[10-minute tutorial](https://docs.activegraph.dev/quickstart/)** — install
+- **[10-minute tutorial](https://docs.activegraph.ai/quickstart/)** — install
   to a working custom behavior, including fork-and-diff.
 - **[CHANGELOG.md](CHANGELOG.md)** — every release, with per-version
   migration notes.
@@ -159,7 +229,9 @@ in [`docs/concepts/relations.md`](https://docs.activegraph.dev/concepts/relation
   [`resume_and_fork.py`](examples/resume_and_fork.py),
   [`llm_claim_extraction.py`](examples/llm_claim_extraction.py),
   [`diligence_with_tools.py`](examples/diligence_with_tools.py),
-  [`operate_a_run.py`](examples/operate_a_run.py).
+  [`operate_a_run.py`](examples/operate_a_run.py),
+  [`babyagi.py`](examples/babyagi.py) — BabyAGI's autonomous agent loop,
+  rebuilt as three reactive behaviors over a shared graph.
 
 ## What this is not
 
@@ -178,17 +250,20 @@ in [`docs/concepts/relations.md`](https://docs.activegraph.dev/concepts/relation
 
 ## Status
 
-**v1.0-rc1** (2026-05). v1.0 final ships after the first-time-user
-gate per [CONTRACT v1.0 #C4](CONTRACT.md#v10-c4-v10-ships-as-v10-rc1-first-time-user-gate-is-owned-externally).
-See [CHANGELOG.md](CHANGELOG.md) for the full v0 → v1.0 history and
+**v1.0 (stable)** (2026-05). The first-time-user gate per
+[CONTRACT v1.0 #C4](CONTRACT.md#v10-c4-v10-ships-as-v10-rc1-first-time-user-gate-is-owned-externally)
+ran through three rcs; v1.0 final ships rc3 plus a tutorial-step-7
+output fix and a README "Concepts at a glance" index. See
+[CHANGELOG.md](CHANGELOG.md) for the full v0 → v1.0 history and
 per-version migration notes.
 
 Major shipped milestones:
 
-- **v1.0 (rc1)** — error hierarchy rewrite with per-error reference
-  pages, doc site at [docs.activegraph.dev](https://docs.activegraph.dev/),
+- **v1.0** — error hierarchy rewrite with per-error reference
+  pages, doc site at [docs.activegraph.ai](https://docs.activegraph.ai/),
   `activegraph quickstart` command, mypy `--strict` and docstring
-  coverage CI gates.
+  coverage CI gates, wheel-completeness and deploy-verification CI
+  gates.
 - **v0.9** — pack format and the Diligence reference pack (8 object
   types, 7 behaviors, 3 tools, recorded fixtures).
 - **v0.8** — operator surface: structured logging, Prometheus

{activegraph-1.0.0rc2 → activegraph-1.0.1}/README.md

@@ -36,12 +36,20 @@ capability.
 
 ```bash
 pip install activegraph                    # core runtime + SQLite store + Diligence pack
-pip install "activegraph[llm]"             # Anthropic provider
+pip install "activegraph[llm]"             # Anthropic + OpenAI providers
+pip install "activegraph[anthropic]"       # Anthropic provider only
+pip install "activegraph[openai]"          # OpenAI provider only (+ tiktoken)
 pip install "activegraph[postgres]"        # Postgres-backed event store
 pip install "activegraph[prometheus]"      # Prometheus metrics
 pip install "activegraph[all]"             # everything
 ```
 
+Both LLM providers expose the same `LLMProvider` Protocol surface;
+swap one for the other without touching `@llm_behavior` definitions.
+The [LLM providers reference](https://docs.activegraph.ai/reference/llm-providers/)
+covers the side-by-side surface and the v1.0.1 limitations
+(OpenAI tool use is a v1.1 candidate).
+
 Python 3.11+. Two hard dependencies (`click` for the CLI, `pydantic`
 for the pack format); persistence backends and provider integrations
 are opt-in extras.
@@ -65,7 +73,54 @@ are opt-in extras.
   8 object types, 7 behaviors, 3 tools, recorded fixtures.
 - **Per-error reference pages.** Every error message ends with a
   `More:` link to a page that explains when it fires, why, and how to
-  fix it. Catalog at [docs.activegraph.dev/reference/errors](https://docs.activegraph.dev/reference/errors/).
+  fix it. Catalog at [docs.activegraph.ai/reference/errors](https://docs.activegraph.ai/reference/errors/).
+
+## Concepts at a glance
+
+The framework's twelve primitives, in roughly the order you meet them
+when reading a trace. Each links to its concept page on the doc site;
+read those when you want depth on one piece.
+
+- **Graph** — objects and typed relations forming the world the
+  framework reasons about. The graph is a projection of the event log;
+  every mutation is an event. [→ concepts/graph](https://docs.activegraph.ai/concepts/graph/)
+- **Events** — the append-only history. Every behavior fires in
+  response to events and produces more events; the trace is the
+  ordered log of all of them. [→ concepts/events](https://docs.activegraph.ai/concepts/events/)
+- **Behaviors** — the unit of reactive code. Function, class, or
+  LLM-backed; declares what events it subscribes to and what it
+  produces. The determinism contract is per-behavior. [→ concepts/behaviors](https://docs.activegraph.ai/concepts/behaviors/)
+- **Relations** — typed edges between objects, with their own
+  behaviors. The relation-behavior primitive — coordination logic on
+  the edge, not on either endpoint — is uncommon in other agent
+  frameworks. [→ concepts/relations](https://docs.activegraph.ai/concepts/relations/)
+- **Patches** — proposed mutations with optimistic concurrency.
+  Behaviors propose patches; the runtime applies or rejects them;
+  rejections are events in their own right. [→ concepts/patches](https://docs.activegraph.ai/concepts/patches/)
+- **Views** — scoped reads of the graph for behavior context. Type
+  filters, depth filters, recent-event windows. Views are how
+  pattern-driven behaviors see only what they need to. [→ concepts/views](https://docs.activegraph.ai/concepts/views/)
+- **Frames** — bounded contexts for a run. Goal, constraints, budget,
+  and the registered behaviors for this frame. A run can have one
+  frame or many. [→ concepts/frames](https://docs.activegraph.ai/concepts/frames/)
+- **Policies** — approval and gating for behavior capabilities. Which
+  behaviors can call which tools, which mutations require human
+  approval, what the runtime refuses. [→ concepts/policies](https://docs.activegraph.ai/concepts/policies/)
+- **Patterns** — the Cypher subset for pattern subscriptions. Beyond
+  event-type + predicate, behaviors can subscribe to graph shapes
+  (claim-cited-by-evidence, task-blocks-task, …) with `NOT EXISTS`
+  and temporal predicates. [→ concepts/patterns](https://docs.activegraph.ai/concepts/patterns/)
+- **Replay** — re-execute a run from its event log. Strict mode
+  re-fires every behavior and fails on divergence; permissive mode
+  reconstructs state without re-firing. The LLM replay cache is what
+  makes fork cheap. [→ concepts/replay](https://docs.activegraph.ai/concepts/replay/)
+- **Forking** — branch any run at any event into an independent
+  fork; structurally diff the fork against the parent. The framework's
+  mechanism for hypothesis testing on agentic systems. [→ concepts/forking](https://docs.activegraph.ai/concepts/forking/)
+- **Failure model** — a behavior failure is a `behavior.failed`
+  event, not an exception. The audit trail captures failures as
+  first-class history. Exceptions live at runtime entry points only.
+  [→ concepts/failure-model](https://docs.activegraph.ai/concepts/failure-model/)
 
 ## A small example
 
@@ -103,14 +158,14 @@ runtime.print_trace()
 
 The `unblock` relation behavior fires only for events touching one of
 its edge endpoints. The conceptual deep-dive on edges-with-logic is
-in [`docs/concepts/relations.md`](https://docs.activegraph.dev/concepts/relations/).
+in [`docs/concepts/relations.md`](https://docs.activegraph.ai/concepts/relations/).
 
 ## Documentation
 
-- **[docs.activegraph.dev](https://docs.activegraph.dev/)** — full doc site:
+- **[docs.activegraph.ai](https://docs.activegraph.ai/)** — full doc site:
   concepts, guides, cookbook, CLI reference, API reference, the
   per-error catalog.
-- **[10-minute tutorial](https://docs.activegraph.dev/quickstart/)** — install
+- **[10-minute tutorial](https://docs.activegraph.ai/quickstart/)** — install
   to a working custom behavior, including fork-and-diff.
 - **[CHANGELOG.md](CHANGELOG.md)** — every release, with per-version
   migration notes.
@@ -122,7 +177,9 @@ in [`docs/concepts/relations.md`](https://docs.activegraph.dev/concepts/relation
   [`resume_and_fork.py`](examples/resume_and_fork.py),
   [`llm_claim_extraction.py`](examples/llm_claim_extraction.py),
   [`diligence_with_tools.py`](examples/diligence_with_tools.py),
-  [`operate_a_run.py`](examples/operate_a_run.py).
+  [`operate_a_run.py`](examples/operate_a_run.py),
+  [`babyagi.py`](examples/babyagi.py) — BabyAGI's autonomous agent loop,
+  rebuilt as three reactive behaviors over a shared graph.
 
 ## What this is not
 
@@ -141,17 +198,20 @@ in [`docs/concepts/relations.md`](https://docs.activegraph.dev/concepts/relation
 
 ## Status
 
-**v1.0-rc1** (2026-05). v1.0 final ships after the first-time-user
-gate per [CONTRACT v1.0 #C4](CONTRACT.md#v10-c4-v10-ships-as-v10-rc1-first-time-user-gate-is-owned-externally).
-See [CHANGELOG.md](CHANGELOG.md) for the full v0 → v1.0 history and
+**v1.0 (stable)** (2026-05). The first-time-user gate per
+[CONTRACT v1.0 #C4](CONTRACT.md#v10-c4-v10-ships-as-v10-rc1-first-time-user-gate-is-owned-externally)
+ran through three rcs; v1.0 final ships rc3 plus a tutorial-step-7
+output fix and a README "Concepts at a glance" index. See
+[CHANGELOG.md](CHANGELOG.md) for the full v0 → v1.0 history and
 per-version migration notes.
 
 Major shipped milestones:
 
-- **v1.0 (rc1)** — error hierarchy rewrite with per-error reference
-  pages, doc site at [docs.activegraph.dev](https://docs.activegraph.dev/),
+- **v1.0** — error hierarchy rewrite with per-error reference
+  pages, doc site at [docs.activegraph.ai](https://docs.activegraph.ai/),
   `activegraph quickstart` command, mypy `--strict` and docstring
-  coverage CI gates.
+  coverage CI gates, wheel-completeness and deploy-verification CI
+  gates.
 - **v0.9** — pack format and the Diligence reference pack (8 object
   types, 7 behaviors, 3 tools, recorded fixtures).
 - **v0.8** — operator surface: structured logging, Prometheus

{activegraph-1.0.0rc2 → activegraph-1.0.1}/activegraph/__init__.py

@@ -9,6 +9,7 @@ from activegraph.behaviors.decorators import (
     clear_registry,
     get_registry,
     llm_behavior,
+    register,
     relation_behavior,
 )
 from activegraph.core.clock import Clock, FrozenClock, TickingClock
@@ -215,8 +216,9 @@ __all__ = [
     "migrate",
     "open_store",
     "parse_store_url",
+    "register",
     "relation_behavior",
     "tool",
 ]
 
-__version__ = "1.0.0rc2"
+__version__ = "1.0.1"

{activegraph-1.0.0rc2 → activegraph-1.0.1}/activegraph/behaviors/decorators.py

@@ -27,14 +27,66 @@ from activegraph.behaviors.base import (
 _REGISTRY: list[Union[Behavior, RelationBehavior]] = []
 
 
-def clear_registry() -> None:
+def clear_registry() -> list[Union[Behavior, RelationBehavior]]:
+    """Empty the global behavior registry and return what was cleared.
+
+    Tests that need isolation between cases call this in a fixture; the
+    return value is the list of removed behaviors in registration
+    order, so multi-run scripts can capture them once and re-register
+    via :func:`register` on each subsequent run without re-importing
+    the modules whose ``@behavior`` decorators populated the registry
+    in the first place. See the *Multi-run scripts* cookbook recipe.
+
+    v1.0.1: the return value is new. v1.0 returned ``None``; callers
+    that ignored the return still work unchanged.
+    """
+    cleared: list[Union[Behavior, RelationBehavior]] = list(_REGISTRY)
     _REGISTRY.clear()
+    return cleared
 
 
 def get_registry() -> list[Union[Behavior, RelationBehavior]]:
+    """Snapshot of the global behavior registry (a shallow copy)."""
     return list(_REGISTRY)
 
 
+def register(behavior_obj: Union[Behavior, RelationBehavior]) -> None:
+    """Append an already-constructed behavior to the global registry.
+
+    The decorators (:func:`behavior`, :func:`relation_behavior`,
+    :func:`llm_behavior`) register on definition; this function exists
+    for the case where definition and registration are decoupled —
+    most commonly, multi-run scripts that call :func:`clear_registry`
+    between runs and need to re-populate the registry without
+    re-importing the decorator-bearing modules:
+
+    .. code-block:: python
+
+        from activegraph import clear_registry, register
+
+        cleared = clear_registry()        # capture before the first run
+        rt1 = Runtime(graph1); rt1.run_goal("first")
+
+        for b in cleared:                 # restore for the next run
+            register(b)
+        rt2 = Runtime(graph2); rt2.run_goal("second")
+
+    See the *Multi-run scripts* cookbook recipe.
+
+    v1.0.1: new. v1.0 required reaching into the private
+    ``_REGISTRY`` list — the user-test gate surfaced that as a rough
+    edge.
+    """
+    if not isinstance(behavior_obj, (Behavior, RelationBehavior)):
+        raise TypeError(
+            f"register() expected a Behavior, RelationBehavior, or "
+            f"LLMBehavior instance; got {type(behavior_obj).__name__}. "
+            f"Use the @behavior / @relation_behavior / @llm_behavior "
+            f"decorators to construct one."
+        )
+    _REGISTRY.append(behavior_obj)
+
+
 def behavior(
     name: Optional[str] = None,
     on: Optional[list[str]] = None,
@@ -124,6 +176,26 @@ def llm_behavior(
 
     Keyword-only on purpose — `@llm_behavior` carries enough
     parameters that positional binding would be a footgun.
+
+    `prompt_template=` is the only escape hatch from the
+    runtime-assembled prompt. It is a `str.format`-style template that
+    receives four placeholders:
+
+    - ``{system}`` — the system block: behavior name, frame goal and
+      constraints, role description, and (when `output_schema=` is set)
+      the schema with an example instance.
+    - ``{view}`` — the scoped graph view: objects, relations, and
+      recent events, rendered as Markdown (format locked per
+      CONTRACT v0.6 #13).
+    - ``{event}`` — the triggering event as id, type, actor, and
+      pretty-printed JSON payload with volatile keys stripped.
+    - ``{instruction}`` — the one-sentence task derived from `creates=`
+      and `output_schema=`.
+
+    The four placeholders carry the same runtime-assembled content
+    whether or not a template is set; the template only re-arranges
+    them. Omitting `prompt_template=` (the default) uses the
+    runtime's canonical layout.
     """
 
     from activegraph.runtime.patterns import parse as _parse_pattern

{activegraph-1.0.0rc2 → activegraph-1.0.1}/activegraph/errors.py

@@ -16,7 +16,7 @@ locked format:
       <concrete action>
 
     More:
-      https://docs.activegraph.dev/errors/<slug>
+      https://docs.activegraph.ai/errors/<slug>
 
 The seven category bases are stable. Concrete leaves are migrated under
 their categories one PR at a time (CONTRACT v1.0 #C1 — the rewrite ships
@@ -25,8 +25,8 @@ as the reference category; subsequent PRs migrate the other categories
 without changing the bases.
 
 `_doc_slug` on each class is the URL slug for the error's doc page. The
-base URL is the github.io fallback (CONTRACT v1.0 #C6); once DNS for
-`docs.activegraph.dev` is live, the constant is swapped in one place.
+base URL is the primary `docs.activegraph.ai` domain (CONTRACT v1.0 #C6,
+v1.0-rc3 amendment); the constant is the single swap point.
 """
 
 from __future__ import annotations
@@ -34,10 +34,13 @@ from __future__ import annotations
 from typing import Any, ClassVar
 
 
-# CONTRACT v1.0 #C6: until docs.activegraph.dev DNS is live, error URLs
-# point at the github.io fallback. The cutover is a one-line edit here
-# plus a README update; the URLs in every error message follow.
-DOCS_BASE_URL = "https://yoheinakajima.github.io/activegraph"
+# CONTRACT v1.0 #C6 (v1.0-rc3 amendment): primary doc-site domain is
+# docs.activegraph.ai. Until the user-owned Pages enablement and DNS
+# land, the URL renders the same 404 the rc2 user-test surfaced; the
+# v1.1 #9 deploy-verification gate fails until that lands, which is
+# the correct signal. One-line swap point: update this constant and
+# every error message URL and `DOCS_BASE_URL`-derived f-string follows.
+DOCS_BASE_URL = "https://docs.activegraph.ai"
 
 
 def _indent_continuation(text: str, indent: str = "  ") -> str:

{activegraph-1.0.0rc2 → activegraph-1.0.1}/activegraph/llm/__init__.py

@@ -1,4 +1,4 @@
-"""LLM behaviors subpackage. CONTRACT v0.6.
+"""LLM behaviors subpackage. CONTRACT v0.6; OpenAIProvider added v1.0.1 #5.
 
 Public surface:
 
@@ -6,6 +6,8 @@ Public surface:
   LLMMessage             — single role-tagged message
   LLMResponse            — what `complete()` returns
   AnthropicProvider      — reference implementation
+  OpenAIProvider         — second concrete provider, surface parity
+                           with AnthropicProvider (v1.0.1 #5)
   RecordedLLMProvider    — fixture-backed provider for tests
   RecordingLLMProvider   — wraps another provider, persists responses
                            as fixtures (for first-time test seed)
@@ -17,11 +19,16 @@ Public surface:
   LLMBehaviorError       — structured failure carrier from @llm_behavior
                            wrappers; runtime turns it into
                            `behavior.failed` with a `reason`
+  parse_structured_response — JSON-extraction-then-Pydantic-validate
+                           helper shared by every provider that uses
+                           the framework's instruction-based path
 """
 
 from activegraph.llm.anthropic import AnthropicProvider
 from activegraph.llm.cache import LLMCache
 from activegraph.llm.errors import LLMBehaviorError, MissingProviderError
+from activegraph.llm.openai import OpenAIProvider
+from activegraph.llm.parsing import parse_structured_response
 from activegraph.llm.prompt import (
     AssembledPrompt,
     assemble_prompt,
@@ -42,10 +49,12 @@ __all__ = [
     "LLMProvider",
     "LLMResponse",
     "MissingProviderError",
+    "OpenAIProvider",
     "RecordedLLMProvider",
     "RecordingLLMProvider",
     "ToolCall",
     "assemble_prompt",
+    "parse_structured_response",
     "schema_to_json",
     "serialize_view",
 ]

{activegraph-1.0.0rc2 → activegraph-1.0.1}/activegraph/llm/anthropic.py

@@ -23,12 +23,12 @@ keeps the surface narrow on purpose.
 from __future__ import annotations
 
 import json
-import re
 import time
 from decimal import Decimal
 from typing import Any, Mapping, Optional
 
 from activegraph.llm.errors import LLMBehaviorError
+from activegraph.llm.parsing import parse_structured_response as _parse_structured
 from activegraph.llm.provider import LLMProvider
 from activegraph.llm.types import LLMMessage, LLMResponse, ToolCall
 
@@ -265,57 +265,6 @@ def _message_to_anthropic(m: LLMMessage) -> dict[str, Any]:
     return {"role": m.role, "content": m.content}
 
 
-_FENCED_JSON_RE = re.compile(r"```(?:json)?\s*(\{.*?\}|\[.*?\])\s*```", re.DOTALL)
-_BRACE_RE = re.compile(r"(\{.*\}|\[.*\])", re.DOTALL)
-
-
-def _parse_structured(text: str, schema: type) -> Any:
-    """Parse JSON out of an LLM response and validate against `schema`.
-
-    Strategy: try direct JSON first; on failure, extract a fenced
-    ```json``` block; on failure, grab the first {...}/[...] span.
-    Two distinct failure modes flow back as `LLMBehaviorError`:
-
-      reason=llm.parse_error      — no JSON found / json.loads failed
-      reason=llm.schema_violation — JSON found but Pydantic rejected it
-    """
-
-    candidate = text.strip()
-    obj: Any = None
-    parse_err: Optional[Exception] = None
-    try:
-        obj = json.loads(candidate)
-    except Exception as e:
-        parse_err = e
-    if obj is None:
-        m = _FENCED_JSON_RE.search(text) or _BRACE_RE.search(text)
-        if m:
-            try:
-                obj = json.loads(m.group(1))
-                parse_err = None
-            except Exception as e:
-                parse_err = e
-    if obj is None:
-        raise LLMBehaviorError(
-            "llm.parse_error",
-            f"no JSON found in response: {parse_err}",
-            payload_extras={"raw_text": text, "underlying": str(parse_err)},
-        )
-
-    try:
-        return schema.model_validate(obj)
-    except Exception as e:
-        raise LLMBehaviorError(
-            "llm.schema_violation",
-            f"response did not match schema {schema.__name__}: {e}",
-            payload_extras={
-                "raw_text": text,
-                "schema": schema.__name__,
-                "validation_errors": str(e),
-            },
-        ) from e
-
-
 def _classify_provider_exception(e: Exception) -> str:
     name = type(e).__name__.lower()
     if "ratelimit" in name or "429" in str(e):