afs-core 0.1.0__tar.gz

afs_core-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# --- OS / editor ---
+.DS_Store
+Thumbs.db
+*.swp
+.idea/
+.vscode/
+
+# --- Python (packages land in M0+) ---
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.uv/
+*.egg-info/
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+.ty_cache/
+dist/
+build/
+
+# --- Node (workers/mcp-edge lands later) ---
+node_modules/
+npm-debug.log*
+
+# --- Secrets / local env ---
+.env
+.env.*
+!.env.example
+*.secret.*
+
+# --- Terraform ---
+# Detailed Terraform ignores live in terraform/.gitignore; these catch any
+# stray state/plan artifacts produced outside that tree.
+*.tfstate
+*.tfstate.*
+*.tfplan
+.terraform/
+
+# Agent worktrees (isolated background-agent checkouts)
+.claude/worktrees/

afs_core-0.1.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: afs-core
+Version: 0.1.0
+Summary: agentic-fs core contracts, DTOs, key scheme, and conformance kits. Depends on pydantic only.
+Project-URL: Homepage, https://github.com/vivekkhimani/agentic-fs
+Project-URL: Repository, https://github.com/vivekkhimani/agentic-fs
+Project-URL: Issues, https://github.com/vivekkhimani/agentic-fs/issues
+Author-email: Vivek Khimani <vivekkhimani07@gmail.com>
+License-Expression: Apache-2.0
+Keywords: agentic-fs,agents,conformance,contracts,filesystem,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.7
+Provides-Extra: testing
+Requires-Dist: pytest-asyncio>=0.24; extra == 'testing'
+Requires-Dist: pytest>=8; extra == 'testing'
+Description-Content-Type: text/markdown
+
+# afs-core
+
+The **contracts** package for agentic-fs: `typing.Protocol` interfaces, pydantic
+DTOs, the single key scheme, the closed error vocabulary, versioned event
+contracts, and the conformance test kits. Depends on **pydantic only** — it
+imports without the server, so connectors and adopters can build against it
+without pulling in `afs-server`.
+
+## Status
+
+Foundations slice (M0, in progress):
+
+- `afs_core.keys` — the **single** definition of the S3 key scheme: build, parse,
+  validate, and `is_indexable()`. Nothing else concatenates a key.
+- `afs_core.errors` — the closed `ErrorCode` vocabulary + the `AfsError`
+  hierarchy (RFC 9457 `problem+json` shape).
+- `afs_core.models` — core DTOs (`Page[T]`, `CatalogEntry`, `ExtractionState`, …)
+  and control records (`TenantRecord`, `NamespaceRecord`, `PrincipalRecord`).
+
+Coming next: `afs_core.contracts` (the async Protocols), `afs_core.testing`
+(conformance kits + in-memory fakes), `afs_core.events`.
+
+## Develop
+
+```bash
+uv sync
+uv run pytest packages/afs-core
+```

afs_core-0.1.0/README.md

@@ -0,0 +1,28 @@
+# afs-core
+
+The **contracts** package for agentic-fs: `typing.Protocol` interfaces, pydantic
+DTOs, the single key scheme, the closed error vocabulary, versioned event
+contracts, and the conformance test kits. Depends on **pydantic only** — it
+imports without the server, so connectors and adopters can build against it
+without pulling in `afs-server`.
+
+## Status
+
+Foundations slice (M0, in progress):
+
+- `afs_core.keys` — the **single** definition of the S3 key scheme: build, parse,
+  validate, and `is_indexable()`. Nothing else concatenates a key.
+- `afs_core.errors` — the closed `ErrorCode` vocabulary + the `AfsError`
+  hierarchy (RFC 9457 `problem+json` shape).
+- `afs_core.models` — core DTOs (`Page[T]`, `CatalogEntry`, `ExtractionState`, …)
+  and control records (`TenantRecord`, `NamespaceRecord`, `PrincipalRecord`).
+
+Coming next: `afs_core.contracts` (the async Protocols), `afs_core.testing`
+(conformance kits + in-memory fakes), `afs_core.events`.
+
+## Develop
+
+```bash
+uv sync
+uv run pytest packages/afs-core
+```

afs_core-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "afs-core"
+version = "0.1.0"
+description = "agentic-fs core contracts, DTOs, key scheme, and conformance kits. Depends on pydantic only."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+authors = [{ name = "Vivek Khimani", email = "vivekkhimani07@gmail.com" }]
+keywords = [
+    "agentic-fs",
+    "agents",
+    "contracts",
+    "conformance",
+    "mcp",
+    "filesystem",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.7",
+]
+
+[project.optional-dependencies]
+# The conformance kits + fakes in ``afs_core.testing`` import pytest at module
+# level. Production adopters get just the contracts (``pip install afs-core``);
+# anyone certifying a store/connector adds ``afs-core[testing]``.
+testing = [
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+]
+
+[project.urls]
+Homepage = "https://github.com/vivekkhimani/agentic-fs"
+Repository = "https://github.com/vivekkhimani/agentic-fs"
+Issues = "https://github.com/vivekkhimani/agentic-fs/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/afs_core"]

afs_core-0.1.0/src/afs_core/__init__.py

@@ -0,0 +1,9 @@
+"""agentic-fs core: contracts, DTOs, the key scheme, and the error vocabulary.
+
+Depends on pydantic only — importable without the server. (``afs_core.testing``
+is intentionally not imported here: it depends on pytest and is opt-in.)
+"""
+
+from afs_core import contracts, errors, keys, models
+
+__all__ = ["contracts", "errors", "keys", "models"]

afs_core-0.1.0/src/afs_core/contracts/__init__.py

@@ -0,0 +1,11 @@
+"""The agentic-fs contracts: async ``typing.Protocol`` interfaces (plan §5).
+
+Structural — adopters implement without importing our hierarchy. Each is proven
+by a conformance kit in :mod:`afs_core.testing`.
+"""
+
+from afs_core.contracts.catalog import CatalogStore
+from afs_core.contracts.normalize import NormalizationError, Normalizer
+from afs_core.contracts.objects import ObjectStore
+
+__all__ = ["CatalogStore", "NormalizationError", "Normalizer", "ObjectStore"]

afs_core-0.1.0/src/afs_core/contracts/catalog.py

@@ -0,0 +1,90 @@
+"""The ``CatalogStore`` contract (plan §5.1).
+
+One contract covers entries + control records + checkpoints + scratch quota, so a
+self-hoster swaps **one** stateful dependency. Structural ``Protocol``, async.
+Certify an impl with ``CatalogStoreConformance`` (afs_core.testing); DynamoDB and
+Postgres are the two reference implementations.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from afs_core.models import (
+    CatalogEntry,
+    ExtractionState,
+    NamespaceRecord,
+    Page,
+    PrincipalRecord,
+    ScratchUsage,
+    SyncCheckpoint,
+    TenantRecord,
+)
+
+
+@runtime_checkable
+class CatalogStore(Protocol):
+    # -- entries (derived index of S3; healable FROM S3) --
+    async def put_entry(self, entry: CatalogEntry) -> None: ...
+
+    async def get_entry(self, tenant_id: str, namespace: str, path: str) -> CatalogEntry | None: ...
+
+    async def delete_entry(
+        self, tenant_id: str, namespace: str, path: str, *, hard: bool = False
+    ) -> None:
+        """Tombstone (soft) by default; ``hard=True`` removes the row entirely."""
+        ...
+
+    async def list_entries(
+        self,
+        tenant_id: str,
+        namespace: str,
+        *,
+        prefix: str = "",
+        include_deleted: bool = False,
+        cursor: str | None = None,
+        limit: int = 1000,
+    ) -> Page[CatalogEntry]: ...
+
+    async def find_by_checksum(self, tenant_id: str, checksum: str) -> list[CatalogEntry]: ...
+
+    async def set_extraction(
+        self, tenant_id: str, namespace: str, path: str, state: ExtractionState
+    ) -> None: ...
+
+    async def list_by_extraction_status(
+        self, status: str, *, cursor: str | None = None, limit: int = 100
+    ) -> Page[CatalogEntry]: ...
+
+    async def tree_version(self, tenant_id: str, namespace: str) -> str:
+        """A token bumped on any write to the namespace — the tree-cache key."""
+        ...
+
+    # -- control records (tenants / namespaces / principals) --
+    async def put_tenant(self, tenant: TenantRecord) -> None: ...
+    async def get_tenant(self, tenant_id: str) -> TenantRecord | None: ...
+    async def list_tenants(
+        self, *, cursor: str | None = None, limit: int = 100
+    ) -> Page[TenantRecord]: ...
+
+    async def put_namespace(self, ns: NamespaceRecord) -> None: ...
+    async def get_namespace(self, tenant_id: str, name: str) -> NamespaceRecord | None: ...
+    async def list_namespaces(self, tenant_id: str) -> list[NamespaceRecord]: ...
+    async def delete_namespace(self, tenant_id: str, name: str) -> None: ...
+
+    async def put_principal(self, p: PrincipalRecord) -> None: ...
+    async def get_principal(self, tenant_id: str, principal_id: str) -> PrincipalRecord | None: ...
+    async def list_principals(self, tenant_id: str) -> list[PrincipalRecord]: ...
+
+    # -- connector checkpoints --
+    async def get_checkpoint(self, tenant_id: str, connector_id: str) -> SyncCheckpoint | None: ...
+    async def put_checkpoint(
+        self, tenant_id: str, connector_id: str, cp: SyncCheckpoint
+    ) -> None: ...
+
+    # -- scratch quota (atomic; raises QuotaExceededError) --
+    async def adjust_scratch_usage(
+        self, tenant_id: str, principal_id: str, *, delta_bytes: int, delta_objects: int
+    ) -> ScratchUsage: ...
+
+    async def get_scratch_usage(self, tenant_id: str, principal_id: str) -> ScratchUsage: ...

afs_core-0.1.0/src/afs_core/contracts/normalize.py

@@ -0,0 +1,40 @@
+"""The ``Normalizer`` contract (plan §5.4) — the extractor/parser seam.
+
+A normalizer turns one raw document into normalized per-page markdown. It is the
+*only* place document parsing lives: text_native, docling, llamaparse, and any
+custom parser are all just `Normalizer`s. The `ExtractionPipeline` (in
+afs-server) orders them into a ladder, applies a quality gate, and degrades to
+`catalog_only` — none of which a normalizer needs to know about.
+
+Adding your own: implement this Protocol, certify it against
+`afs_core.testing.NormalizerConformance`, register it via the `afs.normalizers`
+entry-point group, and name it in the extraction ladder. No core changes.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from afs_core.models import NormalizedDocument, SourceDocument
+
+
+class NormalizationError(Exception):
+    """A normalizer couldn't parse the document. Carries a closed-vocabulary
+    ``reason`` (events v1) so the pipeline can record why and try the next rung."""
+
+    def __init__(self, reason: str, message: str | None = None) -> None:
+        self.reason = reason
+        super().__init__(message or reason)
+
+
+@runtime_checkable
+class Normalizer(Protocol):
+    name: str
+
+    def accepts(self, doc: SourceDocument) -> bool:
+        """Whether this normalizer claims the document (by MIME/extension)."""
+        ...
+
+    async def normalize(self, doc: SourceDocument) -> NormalizedDocument:
+        """Parse ``doc`` into per-page markdown, or raise ``NormalizationError``."""
+        ...

afs_core-0.1.0/src/afs_core/contracts/objects.py

@@ -0,0 +1,44 @@
+"""The ``ObjectStore`` contract (plan §5.2).
+
+Structural ``Protocol`` — adopters implement it without importing our hierarchy
+or depending on ``afs-server``. S3 is the only production impl; the protocol
+exists so MinIO/LocalStack back local dev and an in-memory fake backs tests.
+Certify any impl with ``ObjectStoreConformance`` (afs_core.testing).
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from afs_core.models import ObjectStat, Page, PresignedPut
+
+
+@runtime_checkable
+class ObjectStore(Protocol):
+    async def get(self, key: str, *, start: int | None = None, end: int | None = None) -> bytes:
+        """Fetch an object, optionally a byte range ``[start, end]`` (inclusive)."""
+        ...
+
+    async def put(
+        self, key: str, body: bytes, *, content_type: str | None = None
+    ) -> ObjectStat: ...
+
+    async def delete(self, key: str) -> None: ...
+
+    async def delete_prefix(self, prefix: str) -> int:
+        """Delete every object under ``prefix``; returns the count removed."""
+        ...
+
+    async def stat(self, key: str) -> ObjectStat | None:
+        """Metadata for ``key``, or ``None`` if it does not exist."""
+        ...
+
+    async def list(
+        self, prefix: str, *, cursor: str | None = None, limit: int = 1000
+    ) -> Page[ObjectStat]: ...
+
+    async def presigned_put(
+        self, key: str, *, content_type: str, max_bytes: int, expires_in: int = 900
+    ) -> PresignedPut: ...
+
+    async def presigned_get(self, key: str, *, expires_in: int = 300) -> str: ...

afs_core-0.1.0/src/afs_core/errors.py

@@ -0,0 +1,212 @@
+"""The closed error vocabulary and the ``AfsError`` hierarchy.
+
+Every error agentic-fs raises across the wire carries a code from the closed
+:class:`ErrorCode` enum and serializes to an RFC 9457 ``application/problem+json``
+envelope. The vocabulary is closed on purpose: clients (and the MCP tool layer)
+can branch on a small, stable set of codes instead of parsing prose.
+
+Design note — **misses are 404, never 403** (plan §4.1): a caller must not be
+able to tell "exists but forbidden" from "does not exist", or they could
+enumerate tenants/namespaces/documents. So the not-found errors below all map to
+404 and there is intentionally no 403 for resource access.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any
+
+
+class ErrorCode(StrEnum):
+    """Closed vocabulary of machine-readable error codes."""
+
+    # Request / validation
+    VALIDATION_ERROR = "validation_error"
+    INVALID_KEY = "invalid_key"
+    INVALID_NAMESPACE = "invalid_namespace"
+
+    # Not found (also used to hide forbidden — see module docstring)
+    NOT_FOUND = "not_found"
+    TENANT_NOT_FOUND = "tenant_not_found"
+    NAMESPACE_NOT_FOUND = "namespace_not_found"
+    DOCUMENT_NOT_FOUND = "document_not_found"
+
+    # AuthN / AuthZ
+    UNAUTHENTICATED = "unauthenticated"
+    INSUFFICIENT_SCOPE = "insufficient_scope"
+
+    # Read-path / capability
+    CATALOG_ONLY = "catalog_only"
+    SEARCH_NOT_ENABLED = "search_not_enabled"
+    BUDGET_EXCEEDED = "budget_exceeded"
+
+    # Write-path / quota
+    QUOTA_EXCEEDED = "quota_exceeded"
+    PAYLOAD_TOO_LARGE = "payload_too_large"
+    CONFLICT = "conflict"
+
+    # Extraction
+    EXTRACTION_FAILED = "extraction_failed"
+
+    # Catch-all
+    INTERNAL = "internal"
+
+
+class AfsError(Exception):
+    """Base for every agentic-fs error.
+
+    Carries a closed :class:`ErrorCode`, an HTTP status, and an optional
+    ``detail`` map; serializes to an RFC 9457 problem object via
+    :meth:`to_problem`.
+    """
+
+    code: ErrorCode = ErrorCode.INTERNAL
+    http_status: int = 500
+    title: str = "Internal error"
+
+    def __init__(
+        self,
+        message: str | None = None,
+        *,
+        detail: dict[str, Any] | None = None,
+    ) -> None:
+        self.message = message or self.title
+        self.detail = detail or {}
+        super().__init__(self.message)
+
+    def to_problem(self, *, instance: str | None = None) -> dict[str, Any]:
+        """Render as an RFC 9457 ``application/problem+json`` object."""
+        problem: dict[str, Any] = {
+            "type": f"https://agentic-fs.dev/errors/{self.code.value}",
+            "title": self.title,
+            "status": self.http_status,
+            "code": self.code.value,
+            "detail": self.message,
+        }
+        if instance is not None:
+            problem["instance"] = instance
+        problem.update(self.detail)
+        return problem
+
+
+# --- 4xx: client ---------------------------------------------------------------
+
+
+class ValidationError(AfsError):
+    code = ErrorCode.VALIDATION_ERROR
+    http_status = 400
+    title = "Validation error"
+
+
+class InvalidKeyError(ValidationError):
+    code = ErrorCode.INVALID_KEY
+    title = "Invalid object key"
+
+
+class InvalidNamespaceError(ValidationError):
+    code = ErrorCode.INVALID_NAMESPACE
+    title = "Invalid namespace"
+
+
+class UnauthenticatedError(AfsError):
+    code = ErrorCode.UNAUTHENTICATED
+    http_status = 401
+    title = "Unauthenticated"
+
+
+class InsufficientScopeError(AfsError):
+    code = ErrorCode.INSUFFICIENT_SCOPE
+    http_status = 403
+    title = "Insufficient scope"
+
+
+class NotFoundError(AfsError):
+    """Generic 404. Also the disguise for forbidden resource access (§4.1)."""
+
+    code = ErrorCode.NOT_FOUND
+    http_status = 404
+    title = "Not found"
+
+
+class TenantNotFoundError(NotFoundError):
+    code = ErrorCode.TENANT_NOT_FOUND
+    title = "Tenant not found"
+
+
+class NamespaceNotFoundError(NotFoundError):
+    code = ErrorCode.NAMESPACE_NOT_FOUND
+    title = "Namespace not found"
+
+
+class DocumentNotFoundError(NotFoundError):
+    code = ErrorCode.DOCUMENT_NOT_FOUND
+    title = "Document not found"
+
+
+class ConflictError(AfsError):
+    code = ErrorCode.CONFLICT
+    http_status = 409
+    title = "Conflict"
+
+
+class PayloadTooLargeError(AfsError):
+    code = ErrorCode.PAYLOAD_TOO_LARGE
+    http_status = 413
+    title = "Payload too large"
+
+
+class QuotaExceededError(AfsError):
+    code = ErrorCode.QUOTA_EXCEEDED
+    http_status = 429
+    title = "Quota exceeded"
+
+
+class BudgetExceededError(AfsError):
+    code = ErrorCode.BUDGET_EXCEEDED
+    http_status = 422
+    title = "Budget exceeded"
+
+
+class CatalogOnlyError(AfsError):
+    """The document exists and is cite-able, but its contents aren't readable yet."""
+
+    code = ErrorCode.CATALOG_ONLY
+    http_status = 422
+    title = "Document is catalog-only"
+
+
+class SearchNotEnabledError(AfsError):
+    code = ErrorCode.SEARCH_NOT_ENABLED
+    http_status = 422
+    title = "Search is not enabled"
+
+
+# --- 5xx: server ---------------------------------------------------------------
+
+
+class ExtractionFailedError(AfsError):
+    code = ErrorCode.EXTRACTION_FAILED
+    http_status = 500
+    title = "Extraction failed"
+
+
+__all__ = [
+    "AfsError",
+    "BudgetExceededError",
+    "CatalogOnlyError",
+    "ConflictError",
+    "DocumentNotFoundError",
+    "ErrorCode",
+    "ExtractionFailedError",
+    "InsufficientScopeError",
+    "InvalidKeyError",
+    "InvalidNamespaceError",
+    "NamespaceNotFoundError",
+    "NotFoundError",
+    "PayloadTooLargeError",
+    "QuotaExceededError",
+    "SearchNotEnabledError",
+    "TenantNotFoundError",
+    "UnauthenticatedError",
+    "ValidationError",
+]