afs-server 0.1.0__py3-none-any.whl

afs_server/__init__.py

@@ -0,0 +1,3 @@
+"""agentic-fs server: stores, services, REST + MCP — implements the afs-core contracts."""
+
+__version__ = "0.1.0"

afs_server/app.py

@@ -0,0 +1,75 @@
+"""ASGI application factory.
+
+Assembles the REST surface + the MCP mount (sharing one ``FsService`` in-process,
+no HTTP self-calls), wires the configured stores, and renders every ``AfsError``
+as an RFC 9457 ``application/problem+json`` envelope.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+from afs_core.errors import AfsError
+from afs_server import __version__
+from afs_server.extraction import build_pipeline
+from afs_server.mcp import build_mcp
+from afs_server.routers import fs, ingest, meta
+from afs_server.services import FsService
+from afs_server.settings import load_settings
+from afs_server.stores import get_catalog_store, get_object_store
+
+logger = logging.getLogger("afs_server")
+
+
+async def _afs_error_handler(request: Request, exc: AfsError) -> JSONResponse:
+    return JSONResponse(
+        status_code=exc.http_status,
+        content=exc.to_problem(instance=request.url.path),
+        media_type="application/problem+json",
+    )
+
+
+def create_app() -> FastAPI:
+    settings = load_settings()
+    # Stores are lazy (no I/O / credentials at construction), so we can build the
+    # service + MCP server now and share the service between REST and MCP.
+    catalog = get_catalog_store(settings)
+    objects = get_object_store(settings)
+    fs_service = FsService(catalog, objects)
+    extraction_pipeline = build_pipeline()
+
+    mcp_app = build_mcp(fs_service, settings).http_app(path="/")
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        app.state.settings = settings
+        app.state.catalog = catalog
+        app.state.objects = objects
+        app.state.extraction_pipeline = extraction_pipeline
+        logger.info(
+            "afs-server %s started (object_store=%s, catalog=%s, auth=%s)",
+            __version__,
+            settings.object_store_backend,
+            settings.catalog_backend,
+            settings.auth_mode,
+        )
+        # The MCP session manager runs under its own lifespan — nest it so the
+        # mounted /mcp app works (Starlette does not propagate sub-app lifespans).
+        async with mcp_app.lifespan(app):
+            yield
+
+    app = FastAPI(title="agentic-fs", version=__version__, lifespan=lifespan)
+    app.add_exception_handler(AfsError, _afs_error_handler)  # type: ignore[arg-type]
+    app.include_router(meta.router)
+    app.include_router(fs.router)
+    app.include_router(ingest.router)
+    app.mount("/mcp", mcp_app)
+    return app
+
+
+app = create_app()

afs_server/auth.py

@@ -0,0 +1,70 @@
+"""Authentication → a resolved tenant context.
+
+This slice ships **dev auth only**: a static local principal selected when
+``AFS_AUTH_MODE=dev``. Any other mode fails closed (401) until the OAuth 2.1
+resource server lands — so a misconfigured deployment never silently serves data
+with no identity. No tokens or secrets are baked into the image.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from afs_core.errors import InsufficientScopeError, UnauthenticatedError
+
+if TYPE_CHECKING:
+    from afs_server.settings import Settings
+
+logger = logging.getLogger("afs_server.auth")
+
+# Full scope set — granted to the dev principal only.
+_ALL_SCOPES = frozenset({"fs:read", "fs:search", "fs:write:scratch", "ingest", "admin"})
+
+
+@dataclass(frozen=True)
+class TenantContext:
+    """The authority resolved from a request: who, in which tenant, with what."""
+
+    tenant_id: str
+    principal_id: str
+    scopes: frozenset[str] = field(default_factory=frozenset)
+    # None = all namespaces in the tenant are granted (dev convenience).
+    namespaces: frozenset[str] | None = None
+
+    def require_scope(self, scope: str) -> None:
+        if scope not in self.scopes:
+            raise InsufficientScopeError(f"missing required scope: {scope}")
+
+    def allows_namespace(self, namespace: str) -> bool:
+        return self.namespaces is None or namespace in self.namespaces
+
+
+_dev_warned = False
+
+
+def resolve_dev_context(settings: Settings) -> TenantContext:
+    """The static dev principal. Loud, intentional, never production."""
+    global _dev_warned
+    if not _dev_warned:
+        logger.warning(
+            "AFS_AUTH_MODE=dev — serving with a STATIC dev principal and no token "
+            "verification. Never run this in production."
+        )
+        _dev_warned = True
+    return TenantContext(
+        tenant_id=settings.dev_tenant_id,
+        principal_id=settings.dev_principal_id,
+        scopes=_ALL_SCOPES,
+        namespaces=None,
+    )
+
+
+def resolve_context(settings: Settings) -> TenantContext:
+    if settings.auth_mode == "dev":
+        return resolve_dev_context(settings)
+    # oidc and anything else: not implemented yet → fail closed.
+    raise UnauthenticatedError(
+        f"auth_mode {settings.auth_mode!r} is not available yet; only 'dev' is implemented"
+    )

afs_server/dependencies.py

@@ -0,0 +1,51 @@
+"""Shared FastAPI dependencies (typed aliases keep the routers thin)."""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import TYPE_CHECKING, Annotated
+
+from fastapi import Depends, Request
+
+from afs_server.auth import TenantContext, resolve_context
+from afs_server.services import FsService, IngestService
+from afs_server.settings import Settings, load_settings
+
+if TYPE_CHECKING:
+    from afs_core.contracts import CatalogStore, ObjectStore
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return load_settings()
+
+
+def get_catalog(request: Request) -> CatalogStore:
+    return request.app.state.catalog
+
+
+def get_objects(request: Request) -> ObjectStore:
+    return request.app.state.objects
+
+
+def get_fs_service(request: Request) -> FsService:
+    return FsService(request.app.state.catalog, request.app.state.objects)
+
+
+def get_ingest_service(request: Request) -> IngestService:
+    return IngestService(
+        request.app.state.catalog,
+        request.app.state.objects,
+        request.app.state.extraction_pipeline,
+    )
+
+
+def get_principal(settings: Annotated[Settings, Depends(get_settings)]) -> TenantContext:
+    return resolve_context(settings)
+
+
+SettingsDep = Annotated[Settings, Depends(get_settings)]
+CatalogDep = Annotated["CatalogStore", Depends(get_catalog)]
+FsDep = Annotated[FsService, Depends(get_fs_service)]
+IngestDep = Annotated[IngestService, Depends(get_ingest_service)]
+PrincipalDep = Annotated[TenantContext, Depends(get_principal)]

afs_server/extraction/__init__.py

@@ -0,0 +1,48 @@
+"""Extraction — the pluggable parser layer.
+
+A `Normalizer` (text_native builtin, or a third-party plugin) is selected by name
+into a ladder, exactly like the store registry. Add your own parser: implement
+`afs_core.contracts.Normalizer`, certify it with
+`afs_core.testing.NormalizerConformance`, register it under the `afs.normalizers`
+entry-point group, and name it in the ladder. See `docs/swap-guides/` (extraction).
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import entry_points
+
+from afs_core.contracts import Normalizer
+from afs_server.extraction.pipeline import ExtractionOutcome, ExtractionPipeline
+from afs_server.extraction.text_native import TextNativeNormalizer
+
+_NORMALIZER_ENTRY_GROUP = "afs.normalizers"
+
+# Builtin normalizers: name -> factory.
+_BUILTIN_NORMALIZERS = {
+    "text_native": TextNativeNormalizer,
+}
+
+# Default ladder (config, not code — extended as rungs like docling land).
+DEFAULT_LADDER = ["text_native"]
+
+
+def _build_normalizer(name: str) -> Normalizer:
+    builtin = _BUILTIN_NORMALIZERS.get(name)
+    if builtin is not None:
+        return builtin()
+    for ep in entry_points(group=_NORMALIZER_ENTRY_GROUP):
+        if ep.name == name:
+            return ep.load()()
+    available = sorted(_BUILTIN_NORMALIZERS) + [
+        ep.name for ep in entry_points(group=_NORMALIZER_ENTRY_GROUP)
+    ]
+    raise ValueError(f"unknown normalizer {name!r}; available: {', '.join(available) or 'none'}")
+
+
+def build_pipeline(ladder: list[str] | None = None) -> ExtractionPipeline:
+    """Build the extraction pipeline from a ladder of normalizer names."""
+    names = ladder or DEFAULT_LADDER
+    return ExtractionPipeline([_build_normalizer(n) for n in names])
+
+
+__all__ = ["ExtractionOutcome", "ExtractionPipeline", "build_pipeline"]

afs_server/extraction/pipeline.py

@@ -0,0 +1,50 @@
+"""The extraction pipeline — orders normalizers into a ladder, gates on quality,
+and degrades to catalog_only (plan §5.4, §9.2).
+
+This is the boundary the maintainer's feedback identified: parsers (`Normalizer`s)
+produce a `NormalizedDocument`; the pipeline decides which rung wins and whether
+the result is good enough — neither knows about S3 keys or catalog rows.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from afs_core.contracts import NormalizationError
+
+if TYPE_CHECKING:
+    from afs_core.contracts import Normalizer
+    from afs_core.models import NormalizedDocument, SourceDocument
+
+logger = logging.getLogger("afs_server.extraction")
+
+
+@dataclass(frozen=True)
+class ExtractionOutcome:
+    document: NormalizedDocument
+    extractor: str  # which rung produced it (recorded on the catalog row)
+
+
+class ExtractionPipeline:
+    """Walks the ladder in order; the first rung that accepts the document and
+    produces an above-quality-gate result wins. Returns ``None`` ⇒ catalog_only."""
+
+    def __init__(self, ladder: list[Normalizer], *, min_chars_per_page: int = 1) -> None:
+        self._ladder = ladder
+        self._min_chars = min_chars_per_page
+
+    async def run(self, doc: SourceDocument) -> ExtractionOutcome | None:
+        for nz in self._ladder:
+            if not nz.accepts(doc):
+                continue
+            try:
+                result = await nz.normalize(doc)
+            except NormalizationError as err:
+                logger.info("normalizer %s declined %s: %s", nz.name, doc.filename, err.reason)
+                continue
+            if result.pages and result.quality.min_chars_per_page >= self._min_chars:
+                return ExtractionOutcome(document=result, extractor=nz.name)
+            # below the quality gate — fall through to the next (escalation) rung.
+        return None

afs_server/extraction/text_native.py

@@ -0,0 +1,41 @@
+"""The text_native rung — the first (and cheapest) Normalizer.
+
+Markdown/text/csv/json/html/… are already text, so "extraction" is just reading
+the bytes as one page. The richer rungs (docling for PDFs/Office, llamaparse on
+quality failure) are additional `Normalizer`s registered the same way.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from afs_core.contracts import NormalizationError
+from afs_core.models import NormalizedDocument, PageText, QualityReport
+
+if TYPE_CHECKING:
+    from afs_core.models import SourceDocument
+
+_TEXT_CONTENT_TYPES = {"application/json", "application/xml", "application/x-ndjson"}
+_TEXT_EXTENSIONS = {
+    ".md", ".markdown", ".txt", ".text", ".csv", ".tsv",
+    ".json", ".xml", ".html", ".htm", ".yaml", ".yml", ".log",
+}  # fmt: skip
+
+
+class TextNativeNormalizer:
+    name = "text_native"
+
+    def accepts(self, doc: SourceDocument) -> bool:
+        ct = doc.content_type or ""
+        if ct.startswith("text/") or ct in _TEXT_CONTENT_TYPES:
+            return True
+        return doc.local_path.suffix.lower() in _TEXT_EXTENSIONS
+
+    async def normalize(self, doc: SourceDocument) -> NormalizedDocument:
+        text = doc.local_path.read_bytes().decode("utf-8", errors="replace")
+        if not text.strip():
+            raise NormalizationError("empty_document")
+        return NormalizedDocument(
+            pages=[PageText(number=1, markdown=text, source_locator="text:1")],
+            quality=QualityReport(page_count=1, char_count=len(text), min_chars_per_page=len(text)),
+        )

afs_server/mcp/__init__.py

@@ -0,0 +1,5 @@
+"""MCP surface — FastMCP tools over the shared service layer (no HTTP self-calls)."""
+
+from afs_server.mcp.server import build_mcp
+
+__all__ = ["build_mcp"]

afs_server/mcp/server.py

@@ -0,0 +1,86 @@
+"""The MCP tool surface (FastMCP), backed by the same ``FsService`` the REST
+routes use — shared in-process, no HTTP self-calls (plan §7).
+
+This slice exposes the read-path tools (`whoami`, `fs_list`, `fs_stat`,
+`fs_read`) under the dev principal. The full middleware chain (per-connection
+JWKS auth, claims-filtered `tools/list`, budgets, audit) and the remaining tools
+(`fs_glob`/`fs_grep`/`fs_search`/`scratch_*`) land with their services.
+
+Tools are flat `snake_case`; the docstring **is** the tool description (it states
+the find→read flow and the bounds), per the plan.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from fastmcp import FastMCP
+from fastmcp.exceptions import ToolError
+
+from afs_core.errors import AfsError
+from afs_server.auth import resolve_context
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable
+
+    from pydantic import BaseModel
+
+    from afs_server.services import FsService
+    from afs_server.settings import Settings
+
+
+async def _result(coro: Awaitable[BaseModel]) -> dict[str, Any]:
+    """Await a service call; surface expected AfsErrors as MCP ToolErrors."""
+    try:
+        model = await coro
+    except AfsError as err:
+        raise ToolError(err.message) from err
+    return model.model_dump(mode="json")
+
+
+def build_mcp(fs: FsService, settings: Settings) -> FastMCP:
+    mcp: FastMCP = FastMCP("agentic-fs")
+
+    @mcp.tool
+    async def whoami() -> dict[str, Any]:
+        """Return the calling principal: tenant, scopes, and granted namespaces."""
+        ctx = resolve_context(settings)
+        return {
+            "tenant_id": ctx.tenant_id,
+            "principal_id": ctx.principal_id,
+            "scopes": sorted(ctx.scopes),
+            "namespaces": sorted(ctx.namespaces) if ctx.namespaces is not None else None,
+        }
+
+    @mcp.tool
+    async def fs_list(namespace: str, prefix: str = "", limit: int = 100) -> dict[str, Any]:
+        """List catalog entries in a namespace under an optional path prefix.
+
+        Start here to discover documents, then fs_read to fetch their text.
+        Returns up to `limit` entries and a `next_cursor` to page further.
+        """
+        return await _result(
+            fs.list_entries(resolve_context(settings), namespace, prefix=prefix, limit=limit)
+        )
+
+    @mcp.tool
+    async def fs_stat(namespace: str, path: str) -> dict[str, Any]:
+        """Return one document's catalog record (size, title, extraction status…)."""
+        return await _result(fs.stat(resolve_context(settings), namespace, path))
+
+    @mcp.tool
+    async def fs_read(
+        namespace: str, path: str, start_page: int = 1, end_page: int | None = None
+    ) -> dict[str, Any]:
+        """Read a bounded page range (<= 20 pages) of a document's extracted text.
+
+        A `catalog_only` document exists and is citeable but isn't readable yet —
+        you'll get a tool error saying so; you can still reference it by path.
+        """
+        return await _result(
+            fs.read(
+                resolve_context(settings), namespace, path, start_page=start_page, end_page=end_page
+            )
+        )
+
+    return mcp

afs_server/routers/__init__.py

@@ -0,0 +1 @@
+"""HTTP routers."""

afs_server/routers/fs.py

@@ -0,0 +1,47 @@
+"""Read-path data plane: list / stat / ranged read. Scope: fs:read."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Query
+
+from afs_core.models import CatalogEntry
+from afs_server.dependencies import FsDep, PrincipalDep
+from afs_server.schemas import EntryPage, ReadResponse
+
+router = APIRouter(prefix="/v1/fs", tags=["fs"])
+
+
+@router.get("/{namespace}/entries", response_model=EntryPage)
+async def list_entries(
+    namespace: str,
+    fs: FsDep,
+    principal: PrincipalDep,
+    prefix: Annotated[str, Query()] = "",
+    cursor: Annotated[str | None, Query()] = None,
+    limit: Annotated[int, Query(ge=1, le=1000)] = 100,
+) -> EntryPage:
+    return await fs.list_entries(principal, namespace, prefix=prefix, cursor=cursor, limit=limit)
+
+
+@router.get("/{namespace}/stat", response_model=CatalogEntry)
+async def stat(
+    namespace: str,
+    fs: FsDep,
+    principal: PrincipalDep,
+    path: Annotated[str, Query()],
+) -> CatalogEntry:
+    return await fs.stat(principal, namespace, path)
+
+
+@router.get("/{namespace}/doc", response_model=ReadResponse)
+async def read_doc(
+    namespace: str,
+    fs: FsDep,
+    principal: PrincipalDep,
+    path: Annotated[str, Query()],
+    start_page: Annotated[int, Query(ge=1)] = 1,
+    end_page: Annotated[int | None, Query(ge=1)] = None,
+) -> ReadResponse:
+    return await fs.read(principal, namespace, path, start_page=start_page, end_page=end_page)

afs_server/routers/ingest.py

@@ -0,0 +1,38 @@
+"""Ingestion write path. Scope: ingest."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Query, Request, Response, status
+
+from afs_core.models import CatalogEntry
+from afs_server.dependencies import IngestDep, PrincipalDep
+
+router = APIRouter(prefix="/v1/ingest", tags=["ingest"])
+
+
+@router.put("/{namespace}/doc", response_model=CatalogEntry, status_code=status.HTTP_201_CREATED)
+async def put_doc(
+    namespace: str,
+    request: Request,
+    ingest: IngestDep,
+    principal: PrincipalDep,
+    path: Annotated[str, Query()],
+) -> CatalogEntry:
+    """Upload a document's bytes directly. Text-native files become readable at once."""
+    data = await request.body()
+    return await ingest.put_document(
+        principal, namespace, path, data, content_type=request.headers.get("content-type")
+    )
+
+
+@router.delete("/{namespace}/doc", status_code=status.HTTP_202_ACCEPTED)
+async def delete_doc(
+    namespace: str,
+    ingest: IngestDep,
+    principal: PrincipalDep,
+    path: Annotated[str, Query()],
+) -> Response:
+    await ingest.delete_document(principal, namespace, path)
+    return Response(status_code=status.HTTP_202_ACCEPTED)

afs_server/routers/meta.py

@@ -0,0 +1,38 @@
+"""Meta endpoints: liveness, readiness, whoami."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Response, status
+
+from afs_server import __version__
+from afs_server.dependencies import CatalogDep, PrincipalDep
+from afs_server.schemas import HealthResponse, MeResponse
+
+router = APIRouter(prefix="/v1", tags=["meta"])
+
+
+@router.get("/healthz", response_model=HealthResponse)
+async def healthz() -> HealthResponse:
+    """Liveness — does not touch dependencies."""
+    return HealthResponse(status="ok", version=__version__)
+
+
+@router.get("/readyz", response_model=HealthResponse)
+async def readyz(catalog: CatalogDep, response: Response) -> HealthResponse:
+    """Readiness — confirms the catalog store is reachable."""
+    try:
+        await catalog.list_tenants(limit=1)
+    except Exception:  # readiness reports degraded, never raises
+        response.status_code = status.HTTP_503_SERVICE_UNAVAILABLE
+        return HealthResponse(status="degraded", version=__version__)
+    return HealthResponse(status="ok", version=__version__)
+
+
+@router.get("/me", response_model=MeResponse)
+async def me(principal: PrincipalDep) -> MeResponse:
+    return MeResponse(
+        tenant_id=principal.tenant_id,
+        principal_id=principal.principal_id,
+        scopes=sorted(principal.scopes),
+        namespaces=sorted(principal.namespaces) if principal.namespaces is not None else None,
+    )

afs_server/schemas.py

@@ -0,0 +1,38 @@
+"""Response schemas for the REST surface (snake_case wire format, bounded outputs)."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from afs_core.models import CatalogEntry, Page
+
+
+class HealthResponse(BaseModel):
+    status: str
+    version: str
+
+
+class MeResponse(BaseModel):
+    tenant_id: str
+    principal_id: str
+    scopes: list[str]
+    namespaces: list[str] | None  # None = all namespaces in the tenant
+
+
+# Listing reuses the generic catalog page.
+EntryPage = Page[CatalogEntry]
+
+
+class ReadPage(BaseModel):
+    page: int
+    text: str
+
+
+class ReadResponse(BaseModel):
+    """A bounded, page-ranged read of a document's extracted text."""
+
+    path: str
+    pages: list[ReadPage]
+    page_count: int
+    range: tuple[int, int]
+    truncated: bool

afs_server/services/__init__.py

@@ -0,0 +1,6 @@
+"""Service layer — business logic shared in-process by REST routes and MCP tools."""
+
+from afs_server.services.fs import FsService
+from afs_server.services.ingest import IngestService
+
+__all__ = ["FsService", "IngestService"]