agentenv-framework 0.9.1254__py3-none-any.whl

agent_env/explorer/routers/common.py

@@ -0,0 +1,174 @@
+"""Shared pieces for the explorer's read routers: every list endpoint is
+``DocumentStore.latest_per_id`` + ``count_distinct`` behind one factory, so no route
+depends on a backend query language.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from fastapi import APIRouter, HTTPException, Query
+from pydantic import BaseModel
+
+from agent_env.artifact.registry import canonical_type, equivalent_types
+from agent_env.config import get_config
+from agent_env.store import Filter, Sort
+
+
+class PaginatedResponse(BaseModel):
+    """Pagination envelope shared by every list endpoint."""
+
+    items: list[Any]
+    total: int
+    limit: int
+    offset: int
+    has_more: bool = False
+
+
+def docs():
+    return get_config().get_document_store()
+
+
+def _id_matches(doc: dict, id_field: str, needle: str) -> bool:
+    """Case-insensitive substring match on the entity id."""
+    value = doc.get(id_field)
+    return isinstance(value, str) and needle.lower() in value.lower()
+
+
+_UNIVERSE_FILE_TYPES = {"file_artifact_universe"}
+_UNIVERSE_ENVIRONMENT_TYPES = {"environment_universe"}
+
+
+def _ref_id_version(ref: Any) -> tuple[Optional[str], Optional[int]]:
+    if isinstance(ref, dict):
+        return ref.get("id"), ref.get("version")
+    return (ref if isinstance(ref, str) else None), None
+
+
+def _resolve_doc(store, collection: str, ref: Any) -> Optional[dict]:
+    """Fetch a referenced artifact doc by (id, version); latest version if unpinned."""
+    rid, ver = _ref_id_version(ref)
+    if rid is None:
+        return None
+    if ver is not None:
+        return store.find_one(collection, Filter.of(id=rid, version=ver))
+    found = store.latest_per_id(collection, Filter.of(id=rid))
+    return found[0] if found else None
+
+
+def _enrich_universe(doc: dict, store, collection: str) -> dict:
+    """Resolve a universe's artifact refs into the ``files``/``services`` arrays the UI renders.
+
+    Each file's ``object_url`` is the FileArtifact's seam location, served via /objects/content.
+    """
+    t = doc.get("type")
+    if collection == "artifacts" and isinstance(t, str):
+        t = canonical_type(t)
+    if t in _UNIVERSE_FILE_TYPES:
+        refs = doc.get("file_artifact_refs") or doc.get("file_artifact_ids") or {}
+        files = []
+        for filename, ref in refs.items():
+            fa = _resolve_doc(store, collection, ref)
+            rid, ver = _ref_id_version(ref)
+            files.append({
+                "filename": filename,
+                "artifact_id": rid,
+                "version": ver,
+                "content_type": fa.get("content_type") if fa else None,
+                "object_url": fa.get("s3_url") if fa else None,
+            })
+        doc["files"] = files
+    elif t in _UNIVERSE_ENVIRONMENT_TYPES:
+        refs = doc.get("service_artifact_refs")
+        if not refs:
+            refs = [{"id": sid} for sid in (doc.get("service_artifact_ids") or [])]
+        services = []
+        for ref in refs:
+            sa = _resolve_doc(store, collection, ref)
+            rid, ver = _ref_id_version(ref)
+            services.append({
+                "service_name": (sa.get("service_name") if sa else None) or rid,
+                "artifact_id": rid,
+                "version": ver,
+            })
+        doc["services"] = services
+    return doc
+
+
+def versioned_router(
+    *,
+    prefix: str,
+    tag: str,
+    collection: str,
+    id_field: str = "id",
+) -> APIRouter:
+    """List / get / versions over one ``(id, version)`` collection (artifacts, envs, tasks,
+    agents, evals)."""
+    router = APIRouter(prefix=prefix, tags=[tag])
+
+    @router.get("", response_model=PaginatedResponse)
+    def list_items(
+        limit: int = Query(50, ge=1, le=500),
+        offset: int = Query(0, ge=0),
+        type: Optional[list[str]] = Query(None, description="Filter by type; repeat to union."),
+        id: Optional[str] = Query(None, description="Substring match on the entity id."),
+        sort_by: str = Query("created_at_utc"),
+        descending: bool = Query(True),
+    ) -> PaginatedResponse:
+        store = docs()
+        want_types = set(type) if type else None
+        if want_types is not None and collection == "artifacts":
+            want_types = {s for t in want_types for s in equivalent_types(t)}
+        if id or want_types is not None:
+            # Reduce to the latest version per id FIRST, then filter (by id substring
+            # and/or type) in Python. Filtering before the reduction could select a
+            # superseded version whose type still matches and report it as the live
+            # entity; reducing first means the type filter only ever sees live rows.
+            reduced = store.latest_per_id(
+                collection, Filter({}), id_field=id_field,
+                sort=Sort.by(sort_by, descending=descending),
+            )
+            matched = [
+                d for d in reduced
+                if (not id or _id_matches(d, id_field, id))
+                and (want_types is None or str(d.get("type")) in want_types)
+            ]
+            total = len(matched)
+            items = matched[offset: offset + limit] if limit else matched[offset:]
+        else:
+            items = store.latest_per_id(
+                collection, Filter({}), id_field=id_field,
+                sort=Sort.by(sort_by, descending=descending), limit=limit, offset=offset,
+            )
+            # Count distinct ids, not rows — one entity (N versions) is one result.
+            total = store.count_distinct(collection, Filter({}), id_field=id_field)
+        return PaginatedResponse(
+            items=items, total=total, limit=limit, offset=offset,
+            has_more=offset + len(items) < total,
+        )
+
+    @router.get("/{entity_id}")
+    def get_item(entity_id: str, version: Optional[int] = None) -> dict:
+        store = docs()
+        if version is not None:
+            doc = store.find_one(collection, Filter.of(**{id_field: entity_id, "version": version}))
+        else:
+            found = store.latest_per_id(collection, Filter.of(**{id_field: entity_id}), id_field=id_field)
+            doc = found[0] if found else None
+        if doc is None:
+            raise HTTPException(status_code=404, detail=f"{tag} {entity_id} not found")
+        return _enrich_universe(doc, store, collection)
+
+    @router.get("/{entity_id}/versions")
+    def list_versions(
+        entity_id: str,
+        limit: int = Query(100, ge=1, le=500),
+        offset: int = Query(0, ge=0),
+    ) -> list[dict]:
+        """Every stored version of one entity, newest first. Returns a bare array (not a
+        PaginatedResponse) — clients expect a list here."""
+        filt = Filter.of(**{id_field: entity_id})
+        return docs().query(collection, filt, sort=Sort.by("version", descending=True),
+                            limit=limit, offset=offset)
+
+    return router

agent_env/explorer/routers/conversations.py

@@ -0,0 +1,25 @@
+"""Read-only A2A conversation transcripts, per task instance."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+from agent_env.explorer.routers.common import docs
+from agent_env.store import Filter, Sort
+
+# Prefix hardcoded (not imported from app) to avoid a router->app import cycle.
+router = APIRouter(prefix="/api/v1", tags=["conversations"])
+
+# Written by agent_env.a2a_agent.conversation_store.
+_CONVERSATIONS_COLLECTION = "agent_env_a2a_conversations"
+
+
+@router.get("/task-instances/{task_instance_id}/conversations")
+def list_conversations(task_instance_id: str) -> dict:
+    """A2A conversations recorded for a task instance, oldest first."""
+    conversations = docs().query(
+        _CONVERSATIONS_COLLECTION,
+        Filter.of(task_instance_id=task_instance_id),
+        sort=Sort.by("created_at_utc", descending=False),  # oldest first
+    )
+    return {"conversations": conversations}

agent_env/explorer/routers/objects.py

@@ -0,0 +1,112 @@
+"""Object-store byte seam: stream any object-store blob to the browser."""
+
+from __future__ import annotations
+
+import mimetypes
+import os
+import tempfile
+from urllib.parse import quote
+
+from fastapi import APIRouter, HTTPException, Query
+from fastapi.responses import StreamingResponse
+
+from agent_env.config import get_config
+
+# Prefix hardcoded (not imported from app) to avoid a router->app import cycle.
+router = APIRouter(prefix="/api/v1/objects", tags=["objects"])
+
+_CONTENT_STREAM_CHUNK = 64 * 1024
+
+# Types a browser runs as a document — served under CSP sandbox so a stored
+# HTML/SVG artifact can't execute script on the explorer origin.
+_SANDBOX_TYPES = frozenset({
+    "text/html", "application/xhtml+xml", "image/svg+xml",
+    "application/xml", "text/xml", "application/xslt+xml",
+})
+
+
+def _owned_store(object_url: str):
+    """The store serving ``object_url``, which must be one of its objects: the explorer reads
+    nothing outside the configured store."""
+    store = get_config().get_object_store_at(object_url)
+    if not store.owns(object_url):
+        raise HTTPException(status_code=400, detail="object_url is not in the configured object store")
+    if not store.get_object_key(object_url):
+        raise HTTPException(status_code=400, detail="object_url names a bucket, not an object")
+    return store
+
+
+def _content_disposition(filename: str) -> str:
+    """``inline`` with the name for the browser to save under. Header values are Latin-1, so a
+    name that is not plain ASCII goes in RFC 6266's ``filename*`` beside an ASCII fallback."""
+    fallback = "".join(c if " " <= c <= "~" and c not in '"\\' else "_" for c in filename)
+    if fallback == filename:
+        return f'inline; filename="{filename}"'
+    return f"inline; filename=\"{fallback}\"; filename*=UTF-8''{quote(filename, safe='')}"
+
+
+@router.get("/content")
+def object_content(object_url: str = Query(...)):
+    """Proxy an object-store blob to the browser, resolved through the configured store."""
+    store = _owned_store(object_url)
+    meta = store.get_object_metadata_at(object_url)
+    if meta is None:
+        raise HTTPException(status_code=404, detail="no object at the given object_url")
+
+    # Stream from a temp file to bound memory on large blobs.
+    fd, tmp = tempfile.mkstemp(prefix="agentenv-content-")
+    os.close(fd)
+    try:
+        try:
+            store.download_to_file(object_url, tmp)
+        except Exception:
+            # Object existed at the metadata check above, so a read failure here is an
+            # upstream store error (permission/timeout/outage), not a missing object.
+            raise HTTPException(status_code=502, detail="object store failed to read the object")
+        response = _streamed(tmp, object_url, meta)
+    except BaseException:
+        # The response owns the file once it exists; until then nothing else will remove it.
+        os.unlink(tmp)
+        raise
+    return response
+
+
+def _streamed(tmp: str, object_url: str, meta) -> StreamingResponse:
+    def _stream_and_cleanup():
+        try:
+            with open(tmp, "rb") as fh:
+                while chunk := fh.read(_CONTENT_STREAM_CHUNK):
+                    yield chunk
+        finally:
+            os.unlink(tmp)
+
+    filename = object_url.rstrip("/").rsplit("/", 1)[-1] or "object"
+    # Local stores don't persist a content type; fall back to the filename so both the
+    # media type and the sandbox decision below are correct on every backend.
+    content_type = meta.content_type or mimetypes.guess_type(filename)[0] or "application/octet-stream"
+    headers = {
+        "X-Content-Type-Options": "nosniff",  # untrusted artifact bytes must not sniff-execute
+        "Content-Disposition": _content_disposition(filename),
+    }
+    if content_type.split(";")[0].strip().lower() in _SANDBOX_TYPES:
+        headers["Content-Security-Policy"] = "sandbox"
+    # Reads return the bytes as stored, so the browser needs the encoding to decode them.
+    if meta.content_encoding:
+        headers["Content-Encoding"] = meta.content_encoding
+    if meta.size is not None:
+        headers["Content-Length"] = str(meta.size)
+    return StreamingResponse(
+        _stream_and_cleanup(),
+        media_type=content_type,
+        headers=headers,
+    )
+
+
+@router.get("/metadata")
+def object_metadata(object_url: str = Query(...)):
+    """Size + content-type for an object, without transferring the bytes."""
+    store = _owned_store(object_url)
+    meta = store.get_object_metadata_at(object_url)
+    if meta is None:
+        raise HTTPException(status_code=404, detail="no object at the given object_url")
+    return {"size_bytes": meta.size, "content_type": meta.content_type}