3tears-interfaces 0.93.0__py3-none-any.whl

3tears_interfaces-0.93.0.dist-info/METADATA

@@ -0,0 +1,85 @@
+Metadata-Version: 2.5
+Name: 3tears-interfaces
+Version: 0.93.0
+Summary: Dependency-free Protocols and shared vocabulary for the 3tears family
+Project-URL: Repository, https://github.com/pacepace/3tears
+Author: pace
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# 3tears-interfaces
+
+The 3tears family's shared Protocols and vocabulary, in one package that
+depends on nothing.
+
+**The rule.** This package holds Protocols, the value types and enums that
+cross them, and pure helpers over those types. No implementations, no
+third-party imports, no dependencies. A provider can implement a Protocol, and
+a consumer can accept one, without inheriting any feature package's dependency
+closure. The workspace's `tests/enforcement/` fails any module-top import here
+that is not the stdlib or `threetears.interfaces` itself.
+
+One module per domain:
+
+| Module | What it holds |
+|---|---|
+| `threetears.interfaces.access` | The identity and authorization vocabulary `3tears-iam` and `3tears-agent-acl` both name |
+| `threetears.interfaces.media` | Media capability Protocols, the value types that cross them, and the object-key builder |
+
+## access
+
+```python
+from threetears.interfaces.access import ImpersonationCategory
+```
+
+`ImpersonationCategory` is the fixed set of six sensitive actions: credential,
+passkey and MFA management; account deletion; API-key mint or rotate for the
+target; email change; RBAC grant changes; audit editing. agent-acl deny-lists
+all six under impersonation, and iam's `stepup` requires a recent sign-in for
+each. iam proves who a caller is and agent-acl decides what they may do;
+neither depends on the other, so the values both must agree on live here.
+
+## media
+
+```python
+from threetears.interfaces.media import GeneratedImage, ImageGenerationBackend
+```
+
+The Protocols media providers (`3tears-models`, `3tears-object-store`)
+implement and media consumers (`3tears-agent-tools`) accept: `VisionProvider`,
+`ReferenceVisionProvider`, `TextProvider`, `TranscriptionProvider`,
+`ImageGenerationBackend`, `MediaStorage` and `ObjectStore`. The value types
+that cross them: `MediaInfo`, `GeneratedImage`, `ObjectHandle`,
+`ObjectListing` and `MediaSizeLimitExceeded`. Plus the extraction-status and
+generation-metadata constants, and the object-key builder `build_object_key`.
+
+`MediaFacets` carries the additive carrier facets: rights status, pixel
+dimensions, and whether a locator points at the file itself or at the page
+containing it. The vocabulary grows by addition only, and a consumer that
+does not recognise a facet ignores it rather than failing, so a new carrier
+ships without a coordinated release.
+
+```python
+from threetears.interfaces.media import LOCATOR_KIND_DIRECT_FILE, MediaFacets
+```
+
+## Install
+
+```bash
+pip install 3tears-interfaces
+```
+
+## Versioning policy
+
+`3tears-interfaces` versions in lockstep with the rest of the 3tears
+monorepo: every package shares one version, tracking the framework git tag.

3tears_interfaces-0.93.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+threetears/interfaces/__init__.py,sha256=am8iZx27vAMKWaVyXNSLkBAAVfN5usoKZphwKQXD8q8,1421
+threetears/interfaces/access.py,sha256=Zr1Dk8SWoiHLMVX6KOR44K3G2-umQqFkyFow7pNZ2FM,1714
+threetears/interfaces/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+threetears/interfaces/media/__init__.py,sha256=_QXnyVA-jIJUUsr7LnzA3lJMlauQ9-f-77hxubxC978,1956
+threetears/interfaces/media/facets.py,sha256=Kw6I-U-IK6dWzHk5iUFU7AiAM1v-os2uGdc-QCUhoYY,5918
+threetears/interfaces/media/keys.py,sha256=VcAW89tvkTW381LpFeCIdqYvThYpqzAeY2x9BMWxSr4,6336
+threetears/interfaces/media/protocols.py,sha256=8yYDSRdHqO7TC5AxfkOAqFT6boHUN6InO5YiRvUKjKQ,21994
+3tears_interfaces-0.93.0.dist-info/METADATA,sha256=w0MT4ijoQNqz5NSmHznEPoD7AaZrl46cGgx48Lnpkas,3342
+3tears_interfaces-0.93.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+3tears_interfaces-0.93.0.dist-info/licenses/LICENSE,sha256=7GWEoEOcFJenZLt4LDzqH2K7QLxo_2m8rzG7Vv8VGXo,1066
+3tears_interfaces-0.93.0.dist-info/RECORD,,

3tears_interfaces-0.93.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

3tears_interfaces-0.93.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Pace
+
+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.

threetears/interfaces/__init__.py

@@ -0,0 +1,26 @@
+"""The 3tears family's shared Protocols and vocabulary, in one package that depends on nothing.
+
+One module per domain:
+
+- :mod:`threetears.interfaces.access` -- the identity and authorization vocabulary
+  ``3tears-iam`` (who a caller is) and ``3tears-agent-acl`` (what they may do) both name.
+- :mod:`threetears.interfaces.media` -- the media capability Protocols shared by media
+  providers (``3tears-models``, ``3tears-object-store``) and consumers (``3tears-agent-tools``).
+
+The rule: Protocols, the value types and enums that cross them, and pure helpers over those
+types. No implementations, no third-party imports, no dependencies. A package that speaks
+the vocabulary or implements a Protocol never inherits another feature package's closure by
+doing so. The workspace's ``tests/enforcement/`` enforces it: every module-top import here
+must be the stdlib or ``threetears.interfaces`` itself.
+"""
+
+# Version derived from package metadata so the metadata is the single source of truth: a
+# release that bumps pyproject cannot drift the runtime ``__version__``. ``importlib.metadata``
+# is stdlib, so the dependency-free floor is untouched.
+from importlib.metadata import PackageNotFoundError as _PackageNotFoundError
+from importlib.metadata import version as _version
+
+try:
+    __version__ = _version("3tears-interfaces")
+except _PackageNotFoundError:  # pragma: no cover - dev fallback
+    __version__ = "unknown"

threetears/interfaces/access.py

@@ -0,0 +1,37 @@
+"""The sensitive-action categories authentication and authorization both name.
+
+Two checks guard the same six actions. Authorization (``3tears-agent-acl``'s
+``authorize_from_claims``) refuses them outright under impersonation. Authentication
+(``3tears-iam``'s ``stepup``) lets them through only on a recent sign-in. Each check is
+only as good as its agreement with the other about what the six are, so the set is
+declared once, here, where neither side pays for the other's dependencies to import it.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+__all__ = ["ImpersonationCategory"]
+
+
+class ImpersonationCategory(StrEnum):
+    """The fixed, non-tenant-configurable sensitive-action category set.
+
+    security-model.md's Impersonation paragraph names these six categories verbatim:
+    "credential, passkey, and MFA management; account deletion; API-key mint/rotate for the
+    target; email change; RBAC grant changes; audit editing."
+
+    Two enforcement points read it. Under impersonation every member is deny-listed: there is
+    no partial or tenant-configurable subset. Outside impersonation every member requires
+    step-up re-authentication: the same taxonomy, enforced by freshness instead of subtraction.
+
+    The string values are a wire vocabulary as well as a type: a token, an audit record or a
+    peer repository may carry them, so a member is added, never renamed.
+    """
+
+    CREDENTIAL_PASSKEY_MFA_MANAGEMENT = "credential_passkey_mfa_management"
+    ACCOUNT_DELETION = "account_deletion"
+    APIKEY_MINT_ROTATE_FOR_TARGET = "apikey_mint_rotate_for_target"
+    EMAIL_CHANGE = "email_change"
+    RBAC_GRANT_CHANGE = "rbac_grant_change"
+    AUDIT_EDITING = "audit_editing"

threetears/interfaces/media/__init__.py

@@ -0,0 +1,69 @@
+"""Media capability interfaces.
+
+Pure interface types -- ``typing.Protocol`` classes and stdlib dataclasses -- shared between
+media providers (``3tears-models``, ``3tears-object-store``) and media consumers
+(``3tears-agent-tools``). Implementing or accepting one never inherits a feature package's
+dependency closure: ``3tears-interfaces`` depends on nothing (see :mod:`threetears.interfaces`).
+"""
+
+from threetears.interfaces.media.facets import (
+    LOCATOR_KIND_CONTAINING_PAGE,
+    LOCATOR_KIND_DIRECT_FILE,
+    MediaFacets,
+)
+from threetears.interfaces.media.keys import build_object_key
+from threetears.interfaces.media.protocols import (
+    EXTRACTION_STATUS_COMPLETE,
+    EXTRACTION_STATUS_FAILED,
+    EXTRACTION_STATUS_NONE,
+    EXTRACTION_STATUS_PENDING,
+    EXTRACTION_STATUS_REFUSED,
+    EXTRACTION_STATUS_UNCHANGED,
+    GENERATION_IGNORED,
+    GENERATION_SEED,
+    GENERATION_SIZE,
+    GENERATION_SOURCE_USED,
+    OBJECT_HANDLE_METADATA_KEY,
+    GeneratedImage,
+    ImageGenerationBackend,
+    MediaInfo,
+    MediaSizeLimitExceeded,
+    MediaStorage,
+    ObjectHandle,
+    ObjectListing,
+    ObjectStore,
+    TextProvider,
+    TranscriptionProvider,
+    ReferenceVisionProvider,
+    VisionProvider,
+)
+
+__all__ = [
+    "EXTRACTION_STATUS_COMPLETE",
+    "EXTRACTION_STATUS_FAILED",
+    "EXTRACTION_STATUS_NONE",
+    "EXTRACTION_STATUS_PENDING",
+    "EXTRACTION_STATUS_REFUSED",
+    "EXTRACTION_STATUS_UNCHANGED",
+    "GENERATION_IGNORED",
+    "GENERATION_SEED",
+    "GENERATION_SIZE",
+    "GENERATION_SOURCE_USED",
+    "LOCATOR_KIND_CONTAINING_PAGE",
+    "LOCATOR_KIND_DIRECT_FILE",
+    "OBJECT_HANDLE_METADATA_KEY",
+    "GeneratedImage",
+    "ImageGenerationBackend",
+    "MediaFacets",
+    "MediaInfo",
+    "MediaSizeLimitExceeded",
+    "MediaStorage",
+    "ObjectHandle",
+    "ObjectListing",
+    "ObjectStore",
+    "TextProvider",
+    "TranscriptionProvider",
+    "ReferenceVisionProvider",
+    "VisionProvider",
+    "build_object_key",
+]

threetears/interfaces/media/facets.py

@@ -0,0 +1,131 @@
+"""Carrier facets -- the additive vocabulary a media result may carry.
+
+A facet is the per-carrier detail a *carrier-neutral* result core cannot
+hold: an image's pixel dimensions, the rights it is offered under, whether
+its locator addresses the file itself or the page containing it. The core
+stays carrier-agnostic; facets ride alongside it, keyed by name.
+
+Two rules make the vocabulary safe to grow:
+
+- **Additive only.** A facet is added, never repurposed or removed within a
+  family major. Everything here is optional, and absence means "not known"
+  rather than "not so".
+- **Unrecognised facets are ignored, not rejected.** A producer running a
+  later family version may carry a facet this reader has never heard of, and
+  the reader keeps working -- so :meth:`MediaFacets.from_metadata` drops keys
+  it does not know instead of raising. That is what lets a new carrier ship
+  without a coordinated release across every consumer.
+
+The vocabulary lives here, beside the carrier taxonomy it belongs to
+(:class:`~threetears.interfaces.media.protocols.MediaInfo`'s ``media_category``
+and ``extraction_status``, and the
+:class:`~threetears.interfaces.media.protocols.ObjectHandle` that answers "how
+are the bytes fetchable"), rather than in each retrieval package that produces
+one. A second media vocabulary in a search or discovery leaf is this
+vocabulary, drifting.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+__all__ = [
+    "LOCATOR_KIND_CONTAINING_PAGE",
+    "LOCATOR_KIND_DIRECT_FILE",
+    "MediaFacets",
+]
+
+#: :attr:`MediaFacets.locator_kind`: the locator addresses the media bytes
+#: themselves -- fetching it yields the file.
+LOCATOR_KIND_DIRECT_FILE = "direct-file"
+
+#: :attr:`MediaFacets.locator_kind`: the locator addresses a page the media
+#: appears *on* -- fetching it yields markup, and the bytes need a second step.
+LOCATOR_KIND_CONTAINING_PAGE = "containing-page"
+
+
+@dataclass
+class MediaFacets:
+    """The facets known to this vocabulary, for one media result.
+
+    Every facet is optional and defaults to ``None`` meaning "not reported":
+    a producer fills in what its upstream told it and leaves the rest alone,
+    and a consumer reads only the facets it understands.
+
+    ``rights_status`` is an **open** vocabulary, deliberately: providers
+    report usage rights in labels nobody here controls (a licence identifier,
+    a Creative Commons label, a provider's own bucket name), and coercing
+    those into a closed set would lose the distinction that made a consumer
+    ask. Carry the upstream label verbatim; ``None`` means the provider said
+    nothing, which is not the same as "unrestricted".
+
+    ``locator_kind`` is a *closed* distinction by contrast -- it is ours, not
+    a provider's -- so its two values ship as constants
+    (:data:`LOCATOR_KIND_DIRECT_FILE`, :data:`LOCATOR_KIND_CONTAINING_PAGE`)
+    for callers to compare against rather than as loose strings.
+
+    ``width``/``height`` are pixel dimensions, spelled the way
+    :class:`~threetears.interfaces.media.protocols.GeneratedImage` already
+    spells them so the two can be read across without a translation step.
+    """
+
+    rights_status: str | None = None
+    width: int | None = None
+    height: int | None = None
+    locator_kind: str | None = None  # LOCATOR_KIND_DIRECT_FILE | LOCATOR_KIND_CONTAINING_PAGE
+
+    def to_metadata(self) -> dict[str, Any]:
+        """Project the facets that say something to a JSON-safe dict.
+
+        Unset facets are omitted rather than carried as explicit nulls, so the
+        mapping is exactly the set of facets this result asserts -- a reader
+        iterating its keys never has to tell a reported ``None`` apart from an
+        absent one.
+
+        :return: a JSON-safe mapping of facet name to value, holding only the
+            facets that are set
+        :rtype: dict[str, Any]
+        """
+        facets: dict[str, Any] = {}
+        if self.rights_status is not None:
+            facets["rights_status"] = self.rights_status
+        if self.width is not None:
+            facets["width"] = self.width
+        if self.height is not None:
+            facets["height"] = self.height
+        if self.locator_kind is not None:
+            facets["locator_kind"] = self.locator_kind
+        return facets
+
+    @classmethod
+    def from_metadata(cls, data: dict[str, Any]) -> MediaFacets:
+        """Read the facets this vocabulary knows, ignoring every other key.
+
+        Deliberately lenient where the rest of this package is strict: an
+        unknown key is a facet from a later version of the vocabulary, and
+        dropping it is the contract (a consumer that does not recognise a
+        facet ignores it rather than failing). The leniency stops there --
+        a *known* facet carrying an unusable value still fails, because that
+        is a producer bug rather than a version gap.
+
+        :param data: a facet mapping (as produced by :meth:`to_metadata`),
+            possibly carrying facets this reader does not know
+        :ptype data: dict[str, Any]
+        :return: the facets this vocabulary recognises; absent ones are None
+        :rtype: MediaFacets
+        :raises ValueError: when ``width`` or ``height`` is present but does
+            not read as an integer
+        :raises TypeError: when ``width`` or ``height`` is present but is of
+            a type no integer can be read from
+        """
+        width = data.get("width")
+        height = data.get("height")
+        rights_status = data.get("rights_status")
+        locator_kind = data.get("locator_kind")
+        return cls(
+            rights_status=str(rights_status) if rights_status is not None else None,
+            width=int(width) if width is not None else None,
+            height=int(height) if height is not None else None,
+            locator_kind=str(locator_kind) if locator_kind is not None else None,
+        )

threetears/interfaces/media/keys.py

@@ -0,0 +1,146 @@
+"""Tenant-scoped object-key builder (the platform's scope-first scheme).
+
+The locked layout (scope-and-objects-design.md section 8) is, under one
+bucket per environment::
+
+    <customer_id>/<scope>/<category>/<YYYY>/<MM>/<DD>/<object_id>/<filename>
+
+``customer_id`` is the tenant-isolation prefix; ``scope`` is a
+framework-general owning-context label the producer supplies
+(``engagement-<id>`` / ``conversation-<id>`` / ``agent-<slug>``);
+``object_id`` is a UUIDv7 (unique + time-ordered) folder so derivatives
+co-locate; ``filename`` keeps the original name + extension for human
+readability and correct download naming.
+
+This builder lives in the dependency-free contract (beside
+:class:`~threetears.interfaces.media.protocols.ObjectHandle`) rather than the
+S3 impl package: the layout is a *contract* every producer encodes, and a
+producing tool must be able to build a key without inheriting the aioboto3
+client tree. The impl package re-exports it for back-compat.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime
+from uuid import UUID
+
+__all__ = ["build_object_key"]
+
+#: anything outside the safe key-segment alphabet collapses to a hyphen.
+_UNSAFE = re.compile(r"[^a-z0-9-]+")
+
+#: fallback leaf when no usable filename is supplied.
+_DEFAULT_FILENAME = "object"
+
+#: isolation prefix for objects owned by the platform rather than by one
+#: tenant. the scheme leads with ``customer_id`` because that segment IS the
+#: isolation boundary bucket policy grants on, so a platform-shared object
+#: still needs *a* leading segment to grant against -- it just cannot be a
+#: customer. see :func:`build_object_key`.
+_SHARED_PREFIX = "shared"
+
+
+def _sanitize_segment(value: str) -> str:
+    """Lower-case and collapse ``value`` to the ``[a-z0-9-]`` key alphabet.
+
+    :param value: raw segment (scope label, category, filename stem)
+    :ptype value: str
+    :return: sanitized segment safe as one S3 key path component; falls
+        back to ``object`` when nothing usable remains
+    :rtype: str
+    """
+    cleaned = _UNSAFE.sub("-", value.strip().lower()).strip("-")
+    return cleaned or _DEFAULT_FILENAME
+
+
+def _sanitize_filename(filename: str | None) -> str:
+    """Sanitize a filename's stem while preserving its extension.
+
+    :param filename: original filename (may carry an extension); ``None``
+        or empty yields the ``object`` fallback
+    :ptype filename: str | None
+    :return: readable, key-safe ``<stem>.<ext>`` (or ``<stem>``)
+    :rtype: str
+    """
+    stem, dot, ext = (filename or "").rpartition(".")
+    if not dot:
+        result = _sanitize_segment(filename or "")
+    else:
+        safe_stem = _sanitize_segment(stem)
+        safe_ext = _UNSAFE.sub("", ext.lower())
+        result = f"{safe_stem}.{safe_ext}" if safe_ext else safe_stem
+    return result
+
+
+def build_object_key(
+    *,
+    customer_id: UUID | None,
+    scope: str,
+    category: str,
+    object_id: UUID | None = None,
+    created: datetime | None = None,
+    filename: str | None = None,
+    path: str | None = None,
+) -> str:
+    """Build the scope-first object key (locked design section 8).
+
+    Two shapes, distinguished by whether the object is tenant-owned and
+    whether its address is opaque or meaningful:
+
+    - **tenant-owned, opaque address** (the original and still the common
+      case): ``customer_id`` plus ``object_id`` and ``created`` produce
+      ``<customer_id>/<scope>/<category>/<YYYY>/<MM>/<DD>/<object_id>/<filename>``.
+    - **deterministic address** (``path`` supplied): the caller's own path
+      replaces the date partition, object-id folder and filename. Required
+      when a reader must derive the key from a request without a lookup --
+      a CDN fetching a map tile cannot consult a database to translate
+      ``z/x/y`` into a UUID.
+
+    ``customer_id=None`` addresses a platform-shared object under
+    the ``shared`` prefix instead of a tenant. That is not a loophole in the
+    tenant isolation: ``datasources.customer_id`` is itself nullable
+    with NULL meaning platform-shared, so objects derived from such a row
+    have no tenant to be scoped to, and forcing one would fork a single
+    shared artifact into one copy per customer.
+
+    :param customer_id: verified tenant UUID, or ``None`` for a
+        platform-shared object
+    :ptype customer_id: UUID | None
+    :param scope: owning-context label, e.g. ``engagement-<id>`` (sanitized)
+    :ptype scope: str
+    :param category: object kind, e.g. ``reports`` / ``evidence`` (sanitized)
+    :ptype category: str
+    :param object_id: unique object UUID (UUIDv7, time-ordered); required
+        unless ``path`` is supplied
+    :ptype object_id: UUID | None
+    :param created: UTC creation timestamp; drives the ``YYYY/MM/DD``
+        partition; required unless ``path`` is supplied
+    :ptype created: datetime | None
+    :param filename: original filename + extension; ``None`` -> ``object``
+    :ptype filename: str | None
+    :param path: caller-supplied deterministic tail, replacing the date /
+        object-id / filename segments. Each component is sanitized
+        individually so separators survive, and the final component keeps
+        its extension
+    :ptype path: str | None
+    :return: the full object key
+    :rtype: str
+    :raises ValueError: when neither ``path`` nor both of
+        ``object_id``/``created`` are supplied
+    """
+    owner = str(customer_id) if customer_id is not None else _SHARED_PREFIX
+    head = f"{owner}/{_sanitize_segment(scope)}/{_sanitize_segment(category)}"
+    if path is not None:
+        parts = [part for part in path.split("/") if part]
+        if not parts:
+            raise ValueError("build_object_key: path= must contain at least one component")
+        # the last component is a filename: sanitized as a stem plus extension
+        # so ``98.mvt`` does not collapse to ``98-mvt`` and lose the type a
+        # reader (and a CDN's content negotiation) depends on.
+        tail = "/".join([*(_sanitize_segment(part) for part in parts[:-1]), _sanitize_filename(parts[-1])])
+        return f"{head}/{tail}"
+    if object_id is None or created is None:
+        raise ValueError("build_object_key requires either path=, or both object_id= and created=")
+    leaf = _sanitize_filename(filename)
+    return f"{head}/{created:%Y/%m/%d}/{object_id}/{leaf}"

threetears/interfaces/media/protocols.py

@@ -0,0 +1,618 @@
+"""Protocols for media-related tool capabilities.
+
+These define the contracts that host applications implement. Tool
+implementations can depend on these protocols without coupling to
+any specific infrastructure (S3, specific vision APIs, etc.).
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Protocol, runtime_checkable
+from uuid import UUID
+
+__all__ = [
+    "EXTRACTION_STATUS_COMPLETE",
+    "EXTRACTION_STATUS_FAILED",
+    "EXTRACTION_STATUS_NONE",
+    "EXTRACTION_STATUS_PENDING",
+    "EXTRACTION_STATUS_REFUSED",
+    "EXTRACTION_STATUS_UNCHANGED",
+    "GENERATION_IGNORED",
+    "GENERATION_SEED",
+    "GENERATION_SIZE",
+    "GENERATION_SOURCE_USED",
+    "OBJECT_HANDLE_METADATA_KEY",
+    "GeneratedImage",
+    "ImageGenerationBackend",
+    "MediaInfo",
+    "MediaSizeLimitExceeded",
+    "MediaStorage",
+    "ReferenceVisionProvider",
+    "ObjectHandle",
+    "ObjectListing",
+    "ObjectStore",
+    "TextProvider",
+    "TranscriptionProvider",
+    "VisionProvider",
+]
+
+# ``MediaInfo.extraction_status``: the spellings below are the ones already
+# in the database, and that is deliberately where this vocabulary is
+# defined from. ``agent-memory``'s v021 migration declares the column
+# ``TEXT NOT NULL DEFAULT 'none'`` and v022 builds a partial index on
+# ``WHERE extraction_status = 'pending'`` -- a spelling sitting in a column
+# default and an index predicate is changed by a migration and an index
+# rebuild, not by editing a constant. So these constants name what is
+# stored; they do not propose it (docs/search-spec.md §3.5).
+#
+# The field stays ``str | None``. It is not narrowed to a ``Literal`` or a
+# ``StrEnum``: consumers assign and compare bare ``str`` today, and the
+# column carries no CHECK constraint, so a producer may legitimately store
+# a value this list has not caught up with. Read an unrecognised status the
+# way :mod:`threetears.interfaces.media.facets` reads an unrecognised facet
+# -- ignore it, do not reject it.
+
+#: No extraction has been attempted. The column's server default, and the
+#: value a row carries until something asks for extraction.
+EXTRACTION_STATUS_NONE = "none"
+
+#: Extraction has been requested and has not finished. The value v022's
+#: partial index is built on, which is what makes it a work queue.
+EXTRACTION_STATUS_PENDING = "pending"
+
+#: Extraction finished and the content is available.
+EXTRACTION_STATUS_COMPLETE = "complete"
+
+#: Extraction was attempted and did not produce content -- the fetch died,
+#: the carrier was unreadable, the extractor gave up. Distinct from
+#: :data:`EXTRACTION_STATUS_REFUSED`: something tried and failed.
+EXTRACTION_STATUS_FAILED = "failed"
+
+#: Extraction was declined before it was attempted -- ``robots.txt``
+#: disallowed the fetch, a required extra was absent, a cap refused the
+#: read. Distinct from :data:`EXTRACTION_STATUS_FAILED`: nothing tried, and
+#: retrying under the same rules will decline again.
+EXTRACTION_STATUS_REFUSED = "refused"
+
+#: Upstream confirmed the caller's existing copy is still current, so no
+#: content was produced and none was needed -- an HTTP ``304`` answering a
+#: conditional request (D30 / SR-M4). Distinct from every status above it:
+#: it is a **success**, unlike :data:`EXTRACTION_STATUS_FAILED`; something
+#: did try, unlike :data:`EXTRACTION_STATUS_REFUSED`; and it produced no new
+#: content, unlike :data:`EXTRACTION_STATUS_COMPLETE`.
+#:
+#: A reader that treats "no content" as failure will misread this. The
+#: correct reading is that the caller's own copy is the content, and it has
+#: just been re-confirmed.
+EXTRACTION_STATUS_UNCHANGED = "unchanged"
+
+
+@dataclass
+class GeneratedImage:
+    """Result from an image generation backend."""
+
+    data: bytes
+    mime_type: str
+    width: int | None = None
+    height: int | None = None
+    metadata: dict[str, Any] | None = None
+
+
+@dataclass
+class MediaInfo:
+    """Metadata about a media item, returned by :meth:`MediaStorage.get_media`.
+
+    ``extraction_status`` carries one of the ``EXTRACTION_STATUS_*``
+    constants in this module, or ``None``. ``None`` and
+    :data:`EXTRACTION_STATUS_NONE` both mean *no extraction attempted*:
+    the dataclass defaults to ``None`` while the database column is
+    ``NOT NULL DEFAULT 'none'``, so which one a reader sees depends on
+    whether the value came from a constructor or a row. That split is
+    recorded rather than reconciled -- collapsing it is a migration, not a
+    contract edit -- so a consumer testing for "nothing has happened yet"
+    must accept both.
+
+    ``size_bytes`` is the stored object's size as the storage's catalog
+    records it, or ``None`` when the storage does not know it. It lets a
+    consumer refuse an object that is too large BEFORE downloading it. It is
+    what was recorded, not a measurement, so a consumer that must bound its
+    memory still bounds the read itself (``download_media(max_bytes=...)``).
+    """
+
+    media_id: UUID
+    media_category: str  # "image", "audio", "video", "document"
+    mime_type: str
+    extraction_status: str | None = None
+    has_downloadable_data: bool = True
+    size_bytes: int | None = None
+
+
+class MediaSizeLimitExceeded(Exception):
+    """A bounded download stopped: the media is larger than the limit its caller set.
+
+    Raised by :meth:`MediaStorage.download_media` when called with
+    ``max_bytes``, either before anything is read (the recorded size is over
+    the limit) or as soon as the bytes read pass it. Whatever was read is
+    discarded; the caller never holds more than the limit plus one chunk.
+
+    :param media_id: the media item that was too large
+    :ptype media_id: UUID
+    :param limit_bytes: the limit the caller set
+    :ptype limit_bytes: int
+    :param size_bytes: the recorded size when that is what refused it, or
+        ``None`` when the read passed the limit and the full size is unknown
+    :ptype size_bytes: int | None
+    """
+
+    def __init__(self, media_id: UUID, *, limit_bytes: int, size_bytes: int | None) -> None:
+        """Record which media item passed which limit.
+
+        :param media_id: the media item that was too large
+        :ptype media_id: UUID
+        :param limit_bytes: the limit the caller set
+        :ptype limit_bytes: int
+        :param size_bytes: the recorded size, or ``None`` when unknown
+        :ptype size_bytes: int | None
+        :return: nothing
+        :rtype: None
+        """
+        self.media_id = media_id
+        self.limit_bytes = limit_bytes
+        self.size_bytes = size_bytes
+        detail = f"it is {size_bytes:,} bytes" if size_bytes is not None else "it passed the limit while being read"
+        super().__init__(f"media {media_id} is over the {limit_bytes:,}-byte limit: {detail}")
+
+
+@runtime_checkable
+class ImageGenerationBackend(Protocol):
+    """Protocol for image generation backends.
+
+    What a backend did with what it was given is said in the result's
+    ``metadata``, under the keys :data:`GENERATION_SOURCE_USED`,
+    :data:`GENERATION_IGNORED`, :data:`GENERATION_SIZE` and
+    :data:`GENERATION_SEED`, so the caller can tell the model "the source was not
+    used" or "this model takes no seed" instead of reporting what was asked as
+    what was done. A backend may also carry a ``takes_source_image`` attribute
+    (bool): ``False`` lets a caller refuse an edit before paying for an image
+    made from the words alone. It is not part of the protocol's structure, so a
+    backend without it still satisfies ``isinstance``.
+
+    ``size``, ``aspect`` and ``seed`` are passed only when the caller set them,
+    so a backend written before they existed still takes every call that does
+    not use them.
+    """
+
+    async def generate(
+        self,
+        prompt: str,
+        *,
+        style: str | None = None,
+        source_image: bytes | None = None,
+        source_mime_type: str | None = None,
+        size: str | None = None,
+        aspect: str | None = None,
+        seed: int | None = None,
+    ) -> GeneratedImage:
+        """Generate an image from a text prompt.
+
+        :param prompt: text description of the image to generate
+        :ptype prompt: str
+        :param style: optional style modifier
+        :ptype style: str | None
+        :param source_image: optional source image for img2img
+        :ptype source_image: bytes | None
+        :param source_mime_type: MIME type of source image
+        :ptype source_mime_type: str | None
+        :param size: pixel size as ``"WIDTHxHEIGHT"``, e.g. ``"1024x1536"``
+        :ptype size: str | None
+        :param aspect: shape when no size is given: ``"square"``, ``"landscape"``,
+            ``"portrait"`` or a ratio such as ``"16:9"``
+        :ptype aspect: str | None
+        :param seed: a number that makes the same prompt give the same image again
+        :ptype seed: int | None
+        :return: generated image result
+        :rtype: GeneratedImage
+        """
+        ...
+
+
+#: ``GeneratedImage.metadata`` key: ``True`` when a given source image shaped the
+#: result, ``False`` when the backend made the image from the words alone.
+GENERATION_SOURCE_USED = "source_used"
+
+#: ``GeneratedImage.metadata`` key: the names of the options the backend could not
+#: apply (``"size"``, ``"aspect"``, ``"seed"``, ``"style"``), each with why, as
+#: ``{name: reason}``.
+GENERATION_IGNORED = "ignored"
+
+#: ``GeneratedImage.metadata`` key: the size the image was made at, ``"WIDTHxHEIGHT"``.
+GENERATION_SIZE = "size"
+
+#: ``GeneratedImage.metadata`` key: the seed the image was made with, when the backend has one.
+GENERATION_SEED = "seed"
+
+
+@runtime_checkable
+class MediaStorage(Protocol):
+    """Protocol for media item access and storage.
+
+    Host applications implement this to bridge their specific storage
+    infrastructure (S3, database, etc.) to the generic tool interface.
+    """
+
+    async def get_media(
+        self,
+        media_id: UUID,
+    ) -> MediaInfo | None:
+        """Look up media metadata by ID.
+
+        :param media_id: media item UUID
+        :ptype media_id: UUID
+        :return: media info or None
+        :rtype: MediaInfo | None
+        """
+        ...
+
+    async def download_media(
+        self,
+        media_id: UUID,
+        *,
+        max_bytes: int | None = None,
+    ) -> tuple[bytes, str] | None:
+        """Download raw media bytes, bounded when the caller sets a limit.
+
+        With ``max_bytes`` the implementation refuses an item whose recorded
+        size is over it without reading any of it, and stops reading as soon
+        as the bytes read pass it -- counting as they arrive, because a
+        recorded size can be absent or wrong -- releasing its stream and
+        raising :class:`MediaSizeLimitExceeded`. ``None`` reads the whole item.
+
+        :param media_id: media item UUID
+        :ptype media_id: UUID
+        :param max_bytes: the most bytes the caller will hold, or ``None`` for no limit
+        :ptype max_bytes: int | None
+        :return: (data, mime_type) or None if unavailable
+        :rtype: tuple[bytes, str] | None
+        :raises MediaSizeLimitExceeded: when ``max_bytes`` is set and the item is larger
+        """
+        ...
+
+    async def get_content(
+        self,
+        media_id: UUID,
+        content_type: str,
+        *,
+        model_name: str | None = None,
+    ) -> str | None:
+        """Retrieve extracted content for a media item.
+
+        :param media_id: media item UUID
+        :ptype media_id: UUID
+        :param content_type: type of content to retrieve
+        :ptype content_type: str
+        :param model_name: optional model name filter
+        :ptype model_name: str | None
+        :return: extracted content or None
+        :rtype: str | None
+        """
+        ...
+
+    async def store_content(
+        self,
+        media_id: UUID,
+        user_id: UUID,
+        content_type: str,
+        content: str,
+        metadata: dict[str, Any] | None = None,
+    ) -> str:
+        """Store extracted content for a media item.
+
+        :param media_id: media item UUID
+        :ptype media_id: UUID
+        :param user_id: user who triggered extraction
+        :ptype user_id: UUID
+        :param content_type: type of content being stored
+        :ptype content_type: str
+        :param content: extracted content text
+        :ptype content: str
+        :param metadata: optional metadata
+        :ptype metadata: dict[str, Any] | None
+        :return: content ID
+        :rtype: str
+        """
+        ...
+
+
+@runtime_checkable
+class VisionProvider(Protocol):
+    """Protocol for image analysis via a vision-capable model."""
+
+    async def analyze(
+        self,
+        image_data: bytes,
+        mime_type: str,
+        prompt: str,
+    ) -> str:
+        """Analyze an image and return a text description.
+
+        :param image_data: raw image bytes
+        :ptype image_data: bytes
+        :param mime_type: image MIME type
+        :ptype mime_type: str
+        :param prompt: analysis prompt
+        :ptype prompt: str
+        :return: analysis result text
+        :rtype: str
+        """
+        ...
+
+
+@runtime_checkable
+class ReferenceVisionProvider(Protocol):
+    """Protocol for image analysis by OBJECT REFERENCE, not raw bytes.
+
+    A vision backend that resolves the image itself -- a gateway-backed
+    provider that names the object on the model wire and lets the platform
+    stream the bytes at the model boundary -- implements this instead of
+    :class:`VisionProvider`. The bytes never reach the calling pod, so a
+    provider on this protocol needs no object-store credentials and puts no
+    image on the message bus.
+
+    Additive and separate from :class:`VisionProvider` on purpose: a
+    bytes-taking backend and a reference-taking backend are different
+    capabilities, and a consumer (:mod:`threetears.agent.tools.builtin.analyze_media`)
+    detects which it holds with :func:`isinstance` and routes accordingly. A
+    provider may implement either; a reference-only backend does not have to
+    pretend it can accept bytes it cannot honour.
+
+    Several object ids analyse together in ONE turn, so a multi-image question
+    reaches a vision model as a single interleaved message rather than N
+    separate calls.
+    """
+
+    async def analyze_ref(
+        self,
+        object_ids: list[UUID],
+        prompt: str,
+    ) -> str:
+        """Analyze one or more referenced images and return a text answer.
+
+        :param object_ids: catalogued object ids to analyse together, in order
+        :ptype object_ids: list[UUID]
+        :param prompt: analysis prompt
+        :ptype prompt: str
+        :return: analysis result text
+        :rtype: str
+        """
+        ...
+
+
+@runtime_checkable
+class TextProvider(Protocol):
+    """Protocol for text-only queries (document QA, summarization).
+
+    Separate from :class:`VisionProvider` so that apps can use different
+    models for image analysis vs. text reasoning.  Apps that don't
+    handle documents can ignore this entirely.
+    """
+
+    async def answer(
+        self,
+        prompt: str,
+    ) -> str:
+        """Answer a text prompt.
+
+        :param prompt: text prompt
+        :ptype prompt: str
+        :return: answer text
+        :rtype: str
+        """
+        ...
+
+
+@runtime_checkable
+class TranscriptionProvider(Protocol):
+    """Protocol for audio/video transcription."""
+
+    async def transcribe(
+        self,
+        audio_data: bytes,
+        mime_type: str,
+    ) -> str:
+        """Transcribe audio data to text.
+
+        :param audio_data: raw audio bytes
+        :ptype audio_data: bytes
+        :param mime_type: audio MIME type
+        :ptype mime_type: str
+        :return: transcription text
+        :rtype: str
+        """
+        ...
+
+
+#: the key under which a producing tool places its :class:`ObjectHandle`
+#: (as :meth:`ObjectHandle.to_metadata`) in ``ToolResult.metadata`` so the
+#: agent's catalog seam can recognise + persist it in the object catalog.
+OBJECT_HANDLE_METADATA_KEY = "object_handle"
+
+
+@dataclass
+class ObjectHandle:
+    """Handle to a stored object -- the small descriptor that crosses NATS
+    in place of the bytes.
+
+    The producing tool returns this (in ``ToolResult.metadata`` under
+    :data:`OBJECT_HANDLE_METADATA_KEY`); the agent catalogs it into the
+    hub-owned ``objects`` catalog; consumers resolve ``object_id`` back to
+    ``s3_key`` (customer-safe, pod-side) and stream the bytes down. The bytes
+    themselves never travel with the handle.
+    """
+
+    object_id: UUID
+    s3_key: str
+    mime_type: str
+    size_bytes: int
+    summary: str | None = None
+    category: str | None = None
+
+    def to_metadata(self) -> dict[str, Any]:
+        """Project the handle to a JSON-safe dict for ``ToolResult.metadata``.
+
+        UUIDs are stringified at this border so the descriptor survives the
+        NATS/JSON round-trip to the agent intact.
+
+        :return: a JSON-safe representation of this handle
+        :rtype: dict[str, Any]
+        """
+        return {
+            "object_id": str(self.object_id),
+            "s3_key": self.s3_key,
+            "mime_type": self.mime_type,
+            "size_bytes": self.size_bytes,
+            "summary": self.summary,
+            "category": self.category,
+        }
+
+    @classmethod
+    def from_metadata(cls, data: dict[str, Any]) -> ObjectHandle:
+        """Reconstruct a handle from its :meth:`to_metadata` dict.
+
+        :param data: the JSON-safe handle dict (as produced by
+            :meth:`to_metadata`)
+        :ptype data: dict[str, Any]
+        :return: the reconstructed handle
+        :rtype: ObjectHandle
+        :raises KeyError: when a required field is absent
+        :raises ValueError: when ``object_id`` is not a valid UUID
+        """
+        return cls(
+            object_id=UUID(str(data["object_id"])),
+            s3_key=str(data["s3_key"]),
+            mime_type=str(data["mime_type"]),
+            size_bytes=int(data["size_bytes"]),
+            summary=data.get("summary"),
+            category=data.get("category"),
+        )
+
+
+@dataclass
+class ObjectListing:
+    """One entry from an object-store listing: key plus server metadata.
+
+    Yielded by :meth:`ObjectStore.list_entries` so a reconciler can decide
+    orphan-eligibility by age (``last_modified``) without a per-key HEAD
+    round-trip. ``last_modified`` is the store's own last-modified timestamp
+    (timezone-aware); ``size_bytes`` is the stored object size.
+    """
+
+    key: str
+    last_modified: datetime
+    size_bytes: int
+
+
+@runtime_checkable
+class ObjectStore(Protocol):
+    """Streaming S3-compatible store for large binary artifacts.
+
+    Host apps / the SDK implement this over their object-store
+    infrastructure. STREAMING by contract: writes consume an async byte
+    stream and reads yield one, so a multi-GB artifact (pcap, db dump,
+    rendered report) never has to sit whole in a pod's memory. The key is
+    opaque here; the platform's tenant-scoped key scheme is built above
+    this contract.
+    """
+
+    async def put(
+        self,
+        key: str,
+        body: AsyncIterator[bytes],
+        *,
+        content_type: str,
+        size: int | None = None,
+    ) -> None:
+        """Stream ``body`` to ``key`` (multipart for large objects).
+
+        :param key: tenant-scoped object key (opaque to this contract)
+        :ptype key: str
+        :param body: async iterator yielding the object's bytes in chunks
+        :ptype body: AsyncIterator[bytes]
+        :param content_type: MIME type stored on the object
+        :ptype content_type: str
+        :param size: total byte length when known (lets the impl pick a
+            single PUT below the multipart threshold); None streams multipart
+        :ptype size: int | None
+        :return: nothing
+        :rtype: None
+        """
+        ...
+
+    def open_read(self, key: str) -> AsyncIterator[bytes]:
+        """Open ``key`` for streaming read, yielding bytes in chunks.
+
+        :param key: object key
+        :ptype key: str
+        :return: async iterator over the object's bytes
+        :rtype: AsyncIterator[bytes]
+        """
+        ...
+
+    async def delete(self, key: str) -> None:
+        """Delete a single object.
+
+        :param key: object key
+        :ptype key: str
+        :return: nothing
+        :rtype: None
+        """
+        ...
+
+    async def delete_many(self, keys: list[str]) -> None:
+        """Delete many objects in one batched request (reconciler sweep).
+
+        :param keys: object keys to delete
+        :ptype keys: list[str]
+        :return: nothing
+        :rtype: None
+        """
+        ...
+
+    def list_keys(self, prefix: str | None = None) -> AsyncIterator[str]:
+        """Yield object keys, optionally restricted to ``prefix``.
+
+        :param prefix: key-prefix filter (e.g. a tenant's ``<customer_id>/``);
+            None lists the whole bucket
+        :ptype prefix: str | None
+        :return: async iterator over object keys
+        :rtype: AsyncIterator[str]
+        """
+        ...
+
+    def list_entries(self, prefix: str | None = None) -> AsyncIterator[ObjectListing]:
+        """Yield object listings (key + last-modified + size), optionally by ``prefix``.
+
+        Like :meth:`list_keys` but carries each object's server metadata so a
+        reconciler can judge orphan age without a per-key HEAD request.
+
+        :param prefix: key-prefix filter (e.g. a tenant's ``<customer_id>/``);
+            None lists the whole bucket
+        :ptype prefix: str | None
+        :return: async iterator over object listings
+        :rtype: AsyncIterator[ObjectListing]
+        """
+        ...
+
+    async def presigned_get_url(self, key: str, *, expires_in: int = 300) -> str:
+        """Presigned GET URL for delivery -- bytes never cross the agent.
+
+        :param key: object key
+        :ptype key: str
+        :param expires_in: URL validity in seconds
+        :ptype expires_in: int
+        :return: presigned URL
+        :rtype: str
+        """
+        ...