openframe-core 3.6.0__tar.gz → 3.7.0__tar.gz

{openframe_core-3.6.0 → openframe_core-3.7.0}/.github/CHANGELOG.md

@@ -11,6 +11,130 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## v3.7.0 — 2026-10-11
+
+### Added
+
+- **`openframe.core.remote`** — `RemoteCommandClient[TIn]`/
+  `RemoteQueryClient[TIn, TOut]`, the outbound counterparts of
+  `openframe.core.inbound`'s `CommandHandler`/`QueryHandler`, for
+  `openframe-protocol`'s M1b (HTTP client, service-to-service calls).
+  Structurally identical `execute(input, context) -> result` shape to
+  the inbound pair, but deliberately separate Protocol classes in their
+  own module — direction matters even when the signature doesn't
+  differ, and conflating "something calls into me" with "I call out to
+  something" under one name would erase the distinction this
+  ecosystem's whole organising principle rests on. No `BasePort`/
+  `Identity`/`Capability` involvement: `openframe-protocol`'s own design
+  review (draft 8, decision D10) found no dynamic "give me whichever
+  remote client fills this role" lookup use case exists — a caller
+  always knows exactly which service it's calling — so none of the
+  machinery justifying `Capability`-based registry lookup applies here.
+  Wired by direct construction in a service's own `bootstrap`, the same
+  way `CommandHandler`/`QueryHandler` themselves are never looked up by
+  capability.
+- **`openframe.core.testing.RemoteCommandClientContractTests`/
+  `RemoteQueryClientContractTests`** — extend the existing
+  `CommandHandlerContractTests`/`QueryHandlerContractTests` rather than
+  duplicating their test bodies (only the `isinstance` assertion
+  differs). No new fakes needed either — `SpyCommandHandler`/
+  `SpyQueryHandler` already satisfy the new protocols structurally,
+  confirmed directly rather than assumed.
+- 12 new tests. Full suite: 422 passing (up from 410).
+
+---
+
+## v3.6.0 — 2026-10-09
+
+### Added
+
+- **`openframe.core.ports.BaseGraphStore[T]`** — a new outbound port for
+  graph-store adapters (FalkorDB and similar), defined in
+  `ports/outbound/repository.py` alongside `BaseRepository`/
+  `BaseVectorStore` — same rationale as `BaseVectorStore` for staying in
+  this file rather than its own. Extends `BaseRepository[T]` directly:
+  a graph database's nodes are genuinely id-addressable
+  (create/get/update/delete map onto real `CREATE`/`MATCH ... WHERE
+  n.<key> = $id`/`SET`/`DETACH DELETE` operations), provided the adapter
+  addresses nodes by an application-level unique property (with a
+  backing index/constraint the adapter itself must create) rather than
+  a backend-internal node identity. FalkorDB's own `id()` function is
+  explicitly documented upstream as unstable — deleted nodes' higher
+  internal ids can be migrated down to fill vacated lower ones — which
+  is exactly why adapters must key off their own property, not a reason
+  graph databases don't fit this port. The one operation with no CRUD
+  equivalent is pattern-matching/traversal, so `BaseGraphStore` adds
+  exactly one new method, `traverse(query, params) -> list[T]`, which
+  also serves as the only way to create or query relationships/edges —
+  this port deliberately does not give edges their own method, the same
+  way it does not invent a bespoke query language. Marked
+  `.. stability: experimental`, same as `BaseVectorStore`;
+  `BaseRepository` itself is unaffected and remains stable.
+- **`openframe.core.testing.GraphStoreContractTests`** — extends
+  `RepositoryContractTests` (inherits the full CRUD suite), adds four
+  `traverse()`-specific tests plus a `BaseGraphStore` protocol
+  conformance check. Deliberately query-language-agnostic: rather than
+  hardcoding Cypher syntax, it asks a `traverse_query_for(entity)`
+  fixture for a `(query, params)` pair in whatever language the adapter
+  under test actually speaks — mirroring how `VectorStoreContractTests`
+  asks for an `entity_vector` extractor instead of assuming a specific
+  similarity metric.
+- **`openframe.core.testing.InMemoryGraphStore`** — the matching fake,
+  extending `InMemoryRepository`. Its own `traverse()` is a toy lookup
+  (recognizes a `params["id"]` convention; the `query` string itself is
+  accepted but not interpreted) proving the contract's *shape*, not a
+  query-engine simulation.
+- 27 new tests (23 inherited `RepositoryContractTests`/`PortContractTests`
+  assertions re-run against `InMemoryGraphStore`, plus 4
+  `traverse()`-specific tests). Full suite: 410 passing (up from 383).
+
+---
+
+## v3.5.0 — 2026-10-08
+
+### Added
+
+- **`openframe.core.ports.BaseVectorStore[T]`** — a new outbound port for
+  vector-store adapters (Milvus, Qdrant, ChromaDB), defined in
+  `ports/outbound/repository.py` alongside `BaseRepository` (not its own
+  file — deliberately, so the "why this extends `BaseRepository`"
+  rationale lives next to both classes it concerns). Extends
+  `BaseRepository[T]` directly rather than sitting as a disjoint sibling
+  port — most vector databases are genuinely id-addressable
+  (insert/upsert-with-id, fetch-by-id, delete-by-id, list/scroll), so the
+  five inherited CRUD methods are real operations for them, not fakes
+  forced to satisfy an interface. Adds exactly one new method,
+  `search(query_vector, k) -> list[T]`, the one operation with no
+  equivalent in `BaseRepository`. A vector store satisfying
+  `BaseVectorStore` also satisfies `BaseRepository` for free. Explicitly
+  does **not** target FAISS (a bare in-process index with no native
+  id→metadata store, and some index types that don't support deletion
+  without a full rebuild) or FalkorDB (fundamentally graph-oriented, not
+  id-addressable the same way) — both were evaluated and excluded;
+  graph databases need their own separate port design, not a forced fit
+  here.
+- **`openframe.core.testing.contracts.VectorStoreContractTests`** — the
+  matching contract-test mixin, extending `RepositoryContractTests`
+  (inherits all its CRUD assertions, adds four search-specific ones).
+  Deliberately metric-agnostic: every search assertion uses an
+  exact-match query vector rather than asserting a specific similarity
+  score or ranking among near-ties, since backends default to different
+  metrics (cosine, L2, dot product) that would legitimately rank
+  approximately-similar vectors differently — an exact match ranks
+  first under any reasonable metric, so that's what the contract tests
+  rely on.
+- **`openframe.core.testing.fakes.InMemoryVectorStore`** — the matching
+  fake, extending `InMemoryRepository` unchanged and adding a
+  brute-force Euclidean-distance `search()`. Proven against the full
+  `VectorStoreContractTests` suite in this release's own test suite
+  (27 new tests: 23 inherited CRUD/identity/lifecycle + 4 search-specific).
+- All three pieces are `experimental` — new port, new contract-test
+  mixin, new fake, all added together ahead of the first real adapter
+  packages that will implement `BaseVectorStore` (Milvus, Qdrant,
+  ChromaDB).
+
+---
+
 ## v3.4.0 — 2026-09-28
 
 ### Added
@@ -425,7 +549,10 @@ Dev dependencies: `pytest>=8.0`, `pytest-asyncio>=0.23`, `httpx>=0.27`.
 
 ---
 
-[Unreleased]: https://github.com/openframe-org/openframe-core/compare/v3.4.0...HEAD
+[Unreleased]: https://github.com/openframe-org/openframe-core/compare/v3.7.0...HEAD
+[3.7.0]: https://github.com/openframe-org/openframe-core/compare/v3.6.0...v3.7.0
+[3.6.0]: https://github.com/openframe-org/openframe-core/compare/v3.5.0...v3.6.0
+[3.5.0]: https://github.com/openframe-org/openframe-core/compare/v3.4.0...v3.5.0
 [3.4.0]: https://github.com/openframe-org/openframe-core/compare/v3.3.0...v3.4.0
 [3.3.0]: https://github.com/openframe-org/openframe-core/compare/v3.2.1...v3.3.0
 [3.2.1]: https://github.com/openframe-org/openframe-core/compare/v3.2.0...v3.2.1

{openframe_core-3.6.0 → openframe_core-3.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: openframe-core
-Version: 3.6.0
+Version: 3.7.0
 Summary: OpenFrame Microservice Suite - platform kernel. Port contracts, testing utilities, plugin registry, and composition root.
 Project-URL: Homepage, https://github.com/Furious-Meteors/openframe-core
 Project-URL: Documentation, https://furious-meteors.github.io/openframe-core/

openframe_core-3.7.0/openframe/core/remote/__init__.py

@@ -0,0 +1,23 @@
+"""
+openframe.core.remote
+========================
+Outbound counterparts of openframe.core.inbound's CommandHandler/
+QueryHandler — contracts for a service calling *another service built on
+this platform*, as opposed to `openframe.core.ports.outbound` (third-party
+backend adapters, Capability-tagged) or `openframe.core.inbound`
+(callers reaching into this service).
+
+Added for openframe-protocol's M1b (HTTP client) — see that repo's design
+spec draft 8, section 5.6, decision D10. No BasePort/Capability
+involvement; see `client.py`'s own docstring for why.
+
+.. stability: experimental
+   New alongside the first concrete implementation
+   (`openframe-protocol-http`'s `HttpRemoteQueryClient`/
+   `HttpRemoteCommandClient`). API may change based on real usage.
+"""
+from __future__ import annotations
+
+from openframe.core.remote.client import RemoteCommandClient, RemoteQueryClient
+
+__all__ = ["RemoteCommandClient", "RemoteQueryClient"]

openframe_core-3.7.0/openframe/core/remote/client.py

@@ -0,0 +1,135 @@
+"""
+openframe/core/remote/client.py
+==================================
+RemoteCommandClient, RemoteQueryClient — the outbound counterparts of
+openframe.core.inbound's CommandHandler/QueryHandler (openframe-protocol
+draft 8, section 5.6; D10).
+
+Structurally identical to CommandHandler/QueryHandler — same
+`execute(input, context) -> result` shape — but deliberately a separate
+pair of Protocol classes in their own module, not aliases. Two reasons:
+
+1. Direction matters even when the signature doesn't differ. This
+   ecosystem's entire organising principle (see openframe-protocol's own
+   design history) is driving side vs. driven side, and conflating a
+   "something calls into me" contract with a "I call out to something"
+   contract under one name would erase exactly the distinction that
+   took real design work to land on.
+2. `isinstance(x, RemoteQueryClient)` should read as "this is a remote
+   call" at the call site, not "this happens to satisfy CommandHandler's
+   shape." Structural typing doesn't require the names to differ, but
+   the names carry real information a reader relies on.
+
+No BasePort/Identity/Capability involvement, by design — see draft 8
+section 4's D10 resolution: there is no dynamic "give me whichever
+remote client fills this role" lookup use case (a caller always knows
+exactly which service it's calling), so none of the machinery that
+justifies Capability-based registry lookup applies here. These are
+wired by direct construction in `bootstrap`, the same way `CommandHandler`/
+`QueryHandler` themselves are never looked up by Capability.
+
+Dependency order:
+    inbound/context  → ports/context
+    remote/client    → inbound/context (reuses the same RequestContext —
+                        one request's identity threads through both
+                        directions of a call it triggers, matching how
+                        RequestContext is already shared by inbound).
+"""
+from __future__ import annotations
+
+from typing import Protocol, TypeVar, runtime_checkable
+
+from openframe.core.inbound.context import RequestContext
+
+__all__ = ["RemoteCommandClient", "RemoteQueryClient"]
+
+TInput = TypeVar("TInput")
+TOutput = TypeVar("TOutput")
+
+
+@runtime_checkable
+class RemoteCommandClient(Protocol[TInput]):
+    """
+    Outbound write-side contract — calls another service to mutate its
+    state. The write-side counterpart of
+    :class:`~openframe.core.inbound.command.CommandHandler`, for the
+    opposite direction.
+
+    Adapters/clients satisfy this protocol structurally — no inheritance
+    needed.
+
+    Type parameter:
+        TInput: The command type this client sends.
+
+    Runtime check::
+
+        isinstance(client, RemoteCommandClient)       # ✓ works
+        isinstance(client, RemoteCommandClient[str])  # ✗ raises TypeError
+    """
+
+    async def execute(
+        self,
+        command: TInput,
+        context: RequestContext | None = None,
+    ) -> None:
+        """
+        Send the command to the remote service.
+
+        Args:
+            command: The command to send.
+            context: Optional request context — a real implementation
+                     propagates `context.correlation_id` onward (e.g. as
+                     an outgoing `traceparent`), threading one logical
+                     request's identity through every service it touches.
+
+        Raises:
+            An `AdapterError` subclass on failure — a remote call is, from
+            the caller's perspective, exactly as fallible as a database
+            call, and should surface through the same exception family
+            so callers don't need a separate catch clause for "this
+            dependency happens to be another service" versus "this
+            dependency happens to be a database."
+        """
+        ...
+
+
+@runtime_checkable
+class RemoteQueryClient(Protocol[TInput, TOutput]):
+    """
+    Outbound read-side contract — calls another service and returns its
+    result. The read-side counterpart of
+    :class:`~openframe.core.inbound.query.QueryHandler`, for the
+    opposite direction.
+
+    Type parameters:
+        TInput:  The query type this client sends.
+        TOutput: The result type this client returns.
+
+    Runtime check::
+
+        isinstance(client, RemoteQueryClient)       # ✓ works
+        isinstance(client, RemoteQueryClient[str, int])  # ✗ raises TypeError
+    """
+
+    async def execute(
+        self,
+        query: TInput,
+        context: RequestContext | None = None,
+    ) -> TOutput:
+        """
+        Send the query to the remote service and return its result.
+
+        Args:
+            query:   The query to send.
+            context: Optional request context, propagated onward — see
+                     `RemoteCommandClient.execute`'s own docstring.
+
+        Returns:
+            The remote service's result.
+
+        Raises:
+            An `AdapterError` subclass on failure — see
+            `RemoteCommandClient.execute`'s own docstring for why this
+            family, not a bespoke one.
+        """
+        ...

{openframe_core-3.6.0 → openframe_core-3.7.0}/openframe/core/testing/__init__.py

@@ -42,6 +42,10 @@ from openframe.core.testing.contracts.inbound import (
 from openframe.core.testing.contracts.lifecycle import LifecycleContractTests
 from openframe.core.testing.contracts.port import PortContractTests
 from openframe.core.testing.contracts.producer import ProducerContractTests
+from openframe.core.testing.contracts.remote import (
+    RemoteCommandClientContractTests,
+    RemoteQueryClientContractTests,
+)
 from openframe.core.testing.contracts.repository import RepositoryContractTests
 from openframe.core.testing.contracts.vector_store import VectorStoreContractTests
 from openframe.core.testing.fakes.consumer import FakeConsumer
@@ -74,4 +78,6 @@ __all__ = [
     "UseCaseContractTests",
     "CommandHandlerContractTests",
     "QueryHandlerContractTests",
+    "RemoteCommandClientContractTests",
+    "RemoteQueryClientContractTests",
 ]

{openframe_core-3.6.0 → openframe_core-3.7.0}/openframe/core/testing/contracts/__init__.py

@@ -37,6 +37,10 @@ from openframe.core.testing.contracts.inbound import (
 from openframe.core.testing.contracts.lifecycle import LifecycleContractTests
 from openframe.core.testing.contracts.port import PortContractTests
 from openframe.core.testing.contracts.producer import ProducerContractTests
+from openframe.core.testing.contracts.remote import (
+    RemoteCommandClientContractTests,
+    RemoteQueryClientContractTests,
+)
 from openframe.core.testing.contracts.repository import RepositoryContractTests
 from openframe.core.testing.contracts.vector_store import VectorStoreContractTests
 
@@ -51,4 +55,6 @@ __all__ = [
     "UseCaseContractTests",
     "CommandHandlerContractTests",
     "QueryHandlerContractTests",
+    "RemoteCommandClientContractTests",
+    "RemoteQueryClientContractTests",
 ]

openframe_core-3.7.0/openframe/core/testing/contracts/remote.py

@@ -0,0 +1,79 @@
+"""
+openframe/core/testing/contracts/remote.py
+=============================================
+RemoteCommandClientContractTests, RemoteQueryClientContractTests —
+reusable pytest base classes for `openframe.core.remote`'s outbound
+contracts.
+
+Extends `CommandHandlerContractTests`/`QueryHandlerContractTests` rather
+than duplicating their test bodies — `RemoteCommandClient`/
+`RemoteQueryClient` have the identical `execute()` shape (see
+`remote/client.py`'s own docstring for why they're still separate
+Protocol classes despite that). Only the protocol-conformance assertion
+differs; every other test (return-type shape, context handling) is
+inherited unchanged.
+
+No top-level pytest import — importable without pytest installed,
+matching every other contract module's own convention.
+
+Dependency order:
+    testing/contracts/remote → testing/contracts/inbound, remote
+
+Subclass usage::
+
+    class TestMyRemoteQueryClient(RemoteQueryClientContractTests):
+        @pytest.fixture
+        def query_handler(self) -> MyRemoteQueryClient:
+            return MyRemoteQueryClient()
+"""
+from __future__ import annotations
+
+from openframe.core.testing.contracts.inbound import (
+    CommandHandlerContractTests,
+    QueryHandlerContractTests,
+)
+
+__all__ = ["RemoteCommandClientContractTests", "RemoteQueryClientContractTests"]
+
+
+class RemoteCommandClientContractTests(CommandHandlerContractTests):
+    """
+    Reusable pytest base class for
+    :class:`~openframe.core.remote.RemoteCommandClient` contract tests.
+
+    Subclasses must provide the same `command_handler` fixture
+    `CommandHandlerContractTests` itself requires — the fixture name is
+    unchanged, only the protocol being checked is.
+
+    .. stability: experimental
+    """
+
+    async def test_satisfies_command_handler_protocol(self, command_handler) -> None:
+        """Overridden: checks RemoteCommandClient, not CommandHandler."""
+        from openframe.core.remote import RemoteCommandClient
+
+        assert isinstance(command_handler, RemoteCommandClient), (
+            f"{type(command_handler).__name__} does not satisfy RemoteCommandClient. "
+            "Ensure it has a matching async 'execute' method."
+        )
+
+
+class RemoteQueryClientContractTests(QueryHandlerContractTests):
+    """
+    Reusable pytest base class for
+    :class:`~openframe.core.remote.RemoteQueryClient` contract tests.
+
+    Subclasses must provide the same `query_handler`/`make_query`
+    fixtures `QueryHandlerContractTests` itself requires.
+
+    .. stability: experimental
+    """
+
+    async def test_satisfies_query_handler_protocol(self, query_handler) -> None:
+        """Overridden: checks RemoteQueryClient, not QueryHandler."""
+        from openframe.core.remote import RemoteQueryClient
+
+        assert isinstance(query_handler, RemoteQueryClient), (
+            f"{type(query_handler).__name__} does not satisfy RemoteQueryClient. "
+            "Ensure it has a matching async 'execute' method."
+        )

{openframe_core-3.6.0 → openframe_core-3.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "openframe-core"
-version = "3.6.0"
+version = "3.7.0"
 description = "OpenFrame Microservice Suite - platform kernel. Port contracts, testing utilities, plugin registry, and composition root."
 readme = "README.md"
 requires-python = ">=3.11"