jmfts-client 0.2.0__tar.gz

jmfts_client-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fight Fire with Fire Robotics, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jmfts_client-0.2.0/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: jmfts-client
+Version: 0.2.0
+Summary: Wire contracts and a generated HTTP client for a JMFTS retrieval appliance
+Author: Fight Fire with Fire Robotics, LLC
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jmccardle/jmfts
+Project-URL: Repository, https://github.com/jmccardle/jmfts
+Keywords: jmfts,retrieval,client,api
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.26.0
+Requires-Dist: pydantic>=2.5.0
+Provides-Extra: vectors
+Requires-Dist: numpy>=1.26.0; extra == "vectors"
+Dynamic: license-file
+
+# jmfts-client
+
+The thin half of [JMFTS](https://github.com/jmccardle/jmfts): the wire contracts, and an
+HTTP client generated from them.
+
+Install this to **call** a JMFTS appliance. Install `jmfts` to **run** one.
+
+```bash
+pip install jmfts-client
+```
+
+Two dependencies — `httpx` and `pydantic`. A consumer that only makes requests does not
+install sqlalchemy, psycopg2, pgvector, transformers or pymupdf to do it.
+
+## Use
+
+```python
+from jmfts_client import RemoteJmftsClient
+from jmfts_client.contracts import DocumentCreate, HybridSearchRequest
+
+with RemoteJmftsClient("http://localhost:8100", token="...") as jmfts:
+    doc = jmfts.create_document(DocumentCreate(title="Ada", content="Ada Lovelace"))
+    hits = jmfts.hybrid_search(HybridSearchRequest(query="Ada", limit=10))
+    for hit in hits.results:
+        print(hit.document_id, hit.score)
+```
+
+Errors arrive as exceptions carrying the status: `JmftsNotFound`, `JmftsBadRequest`,
+`JmftsConflict`, `JmftsUnprocessable`, `JmftsServerError`. All descend from `JmftsError`.
+A request that never reached the server raises `JmftsTransportError`.
+
+## Where the methods come from
+
+Nobody writes them. A JMFTS service method marked `@expose` becomes a REST route, an entry
+in the OpenAPI document, a method on the in-process `LocalJmftsClient`, and a method here —
+four views of one definition.
+
+`jmfts_client/_verbs.py` is generated from the route table the server actually builds, not
+from the decorator's declaration, because the decorator does not record which parameters
+are body, query or path — FastAPI's inference decides that, and reading the built routes is
+what keeps this client and the server agreeing about the wire. Regeneration lives in the
+`jmfts` repository (`python -m scripts.generate_client`), and a test there fails if this
+file falls behind the surface.
+
+## What this client does not offer
+
+`LocalJmftsClient.unit_of_work()` groups several writes into one transaction. There is no
+equivalent here, deliberately. Each HTTP request is its own transaction on the server, so a
+`unit_of_work` over HTTP could group the calls but could not roll back the earlier ones when
+a later one failed. If you need that guarantee, run in-process with `jmfts` installed.
+
+## Licence
+
+MIT. Copyright (c) 2026 Fight Fire with Fire Robotics, LLC.

jmfts_client-0.2.0/README.md

@@ -0,0 +1,54 @@
+# jmfts-client
+
+The thin half of [JMFTS](https://github.com/jmccardle/jmfts): the wire contracts, and an
+HTTP client generated from them.
+
+Install this to **call** a JMFTS appliance. Install `jmfts` to **run** one.
+
+```bash
+pip install jmfts-client
+```
+
+Two dependencies — `httpx` and `pydantic`. A consumer that only makes requests does not
+install sqlalchemy, psycopg2, pgvector, transformers or pymupdf to do it.
+
+## Use
+
+```python
+from jmfts_client import RemoteJmftsClient
+from jmfts_client.contracts import DocumentCreate, HybridSearchRequest
+
+with RemoteJmftsClient("http://localhost:8100", token="...") as jmfts:
+    doc = jmfts.create_document(DocumentCreate(title="Ada", content="Ada Lovelace"))
+    hits = jmfts.hybrid_search(HybridSearchRequest(query="Ada", limit=10))
+    for hit in hits.results:
+        print(hit.document_id, hit.score)
+```
+
+Errors arrive as exceptions carrying the status: `JmftsNotFound`, `JmftsBadRequest`,
+`JmftsConflict`, `JmftsUnprocessable`, `JmftsServerError`. All descend from `JmftsError`.
+A request that never reached the server raises `JmftsTransportError`.
+
+## Where the methods come from
+
+Nobody writes them. A JMFTS service method marked `@expose` becomes a REST route, an entry
+in the OpenAPI document, a method on the in-process `LocalJmftsClient`, and a method here —
+four views of one definition.
+
+`jmfts_client/_verbs.py` is generated from the route table the server actually builds, not
+from the decorator's declaration, because the decorator does not record which parameters
+are body, query or path — FastAPI's inference decides that, and reading the built routes is
+what keeps this client and the server agreeing about the wire. Regeneration lives in the
+`jmfts` repository (`python -m scripts.generate_client`), and a test there fails if this
+file falls behind the surface.
+
+## What this client does not offer
+
+`LocalJmftsClient.unit_of_work()` groups several writes into one transaction. There is no
+equivalent here, deliberately. Each HTTP request is its own transaction on the server, so a
+`unit_of_work` over HTTP could group the calls but could not roll back the earlier ones when
+a later one failed. If you need that guarantee, run in-process with `jmfts` installed.
+
+## Licence
+
+MIT. Copyright (c) 2026 Fight Fire with Fire Robotics, LLC.

jmfts_client-0.2.0/jmfts_client/__init__.py

@@ -0,0 +1,91 @@
+"""JMFTS client — the wire contracts, and an HTTP client generated from them.
+
+This distribution is the thin half of JMFTS. It carries ``httpx`` and ``pydantic`` and
+nothing else, so a consumer that only needs to CALL an appliance does not install
+sqlalchemy, pgvector, transformers or pymupdf to do it.
+
+The server distribution (``jmfts``) depends on this one rather than the other way round.
+That direction looks inverted and is deliberate: ``jmfts_client.contracts`` is the single
+definition of every request and response shape, and both the in-process
+``LocalJmftsClient`` and this ``RemoteJmftsClient`` must validate against the SAME classes.
+Shipping a copy to each side would make them equal by value and unequal by ``isinstance``
+— a bug that appears only when one process holds both, which is exactly what
+``JMFTS_RUNNER_URL`` (one appliance embedding against another over HTTP) does.
+
+Imports here are LAZY, through :pep:`562`. The server imports ``jmfts_client.contracts.*``
+in dozens of modules, and an eager ``__init__`` would make every one of those build the
+94-method verb table and import ``httpx`` on the way to one Pydantic class. Laziness also
+keeps the import graph shallow enough that a contract can never close a cycle back through
+the client.
+"""
+
+from typing import TYPE_CHECKING
+
+__version__ = "0.2.0"
+
+if TYPE_CHECKING:  # import-time cost avoided at runtime, type checkers still see the names
+    from jmfts_client.errors import (
+        JmftsBadRequest,
+        JmftsConflict,
+        JmftsError,
+        JmftsForbidden,
+        JmftsNotFound,
+        JmftsResponseError,
+        JmftsServerError,
+        JmftsTransportError,
+        JmftsUnauthorized,
+        JmftsUnprocessable,
+    )
+    from jmfts_client.remote import RemoteJmftsClient
+    from jmfts_client.transport import DEFAULT_BASE_URL, DEFAULT_TIMEOUT
+
+#: Public name -> the module that defines it.
+_LAZY: dict[str, str] = {
+    "DEFAULT_BASE_URL": "jmfts_client.transport",
+    "DEFAULT_TIMEOUT": "jmfts_client.transport",
+    "JmftsBadRequest": "jmfts_client.errors",
+    "JmftsConflict": "jmfts_client.errors",
+    "JmftsError": "jmfts_client.errors",
+    "JmftsForbidden": "jmfts_client.errors",
+    "JmftsNotFound": "jmfts_client.errors",
+    "JmftsResponseError": "jmfts_client.errors",
+    "JmftsServerError": "jmfts_client.errors",
+    "JmftsTransportError": "jmfts_client.errors",
+    "JmftsUnauthorized": "jmfts_client.errors",
+    "JmftsUnprocessable": "jmfts_client.errors",
+    "RemoteJmftsClient": "jmfts_client.remote",
+}
+
+
+def __getattr__(name: str):
+    """Resolve a public name on first use. Anything unlisted is a real AttributeError."""
+    module_name = _LAZY.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    import importlib
+
+    value = getattr(importlib.import_module(module_name), name)
+    globals()[name] = value  # resolved once; later lookups skip this hook
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)
+
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "DEFAULT_TIMEOUT",
+    "JmftsBadRequest",
+    "JmftsConflict",
+    "JmftsError",
+    "JmftsForbidden",
+    "JmftsNotFound",
+    "JmftsResponseError",
+    "JmftsServerError",
+    "JmftsTransportError",
+    "JmftsUnauthorized",
+    "JmftsUnprocessable",
+    "RemoteJmftsClient",
+    "__version__",
+]