deepagents-okf-backend 0.1.0__py3-none-any.whl

deepagents_okf_backend/__init__.py

@@ -0,0 +1,22 @@
+"""OKF-aware filesystem backend for LangChain Deep Agents."""
+
+from __future__ import annotations
+
+from .backend import OKFBackend
+from .frontmatter import parse_frontmatter, serialize_frontmatter
+from .okf import KNOWN_FIELDS, REQUIRED_FIELDS, validate_metadata
+from .query import OKFHit, make_okf_query_tool, query_bundle
+
+__all__ = [
+    "OKFBackend",
+    "OKFHit",
+    "make_okf_query_tool",
+    "query_bundle",
+    "parse_frontmatter",
+    "serialize_frontmatter",
+    "validate_metadata",
+    "REQUIRED_FIELDS",
+    "KNOWN_FIELDS",
+]
+
+__version__ = "0.1.0"

deepagents_okf_backend/backend.py

@@ -0,0 +1,376 @@
+"""OKF-aware filesystem backend for LangChain Deep Agents.
+
+``OKFBackend`` implements deepagents' ``BackendProtocol`` over an Open Knowledge
+Format (OKF) bundle: a directory of markdown files with YAML frontmatter. Reads and
+searches work like a normal virtual filesystem; writes to ``.md`` documents are
+validated as OKF and (optionally) auto-stamped with a ``timestamp``.
+
+Every method returns a structured result with an ``error`` field and never raises —
+this is the ``BackendProtocol`` contract. All disk IO is therefore guarded, and every
+path (including entries discovered by ``ls``/``glob``/``grep``) is confined to the
+bundle root, so a symlink inside the bundle cannot leak files from outside it.
+
+OKF spec: https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Iterable
+from datetime import datetime, timezone
+from pathlib import Path
+
+from deepagents.backends.protocol import (
+    BackendProtocol,
+    EditResult,
+    FileData,
+    FileDownloadResponse,
+    FileInfo,
+    FileUploadResponse,
+    GlobResult,
+    GrepMatch,
+    GrepResult,
+    LsResult,
+    ReadResult,
+    WriteResult,
+)
+
+from .frontmatter import parse_frontmatter, serialize_frontmatter
+from .okf import is_okf_document, validate_metadata
+
+DEFAULT_READ_LIMIT = 2000
+
+
+class _PathEscapeError(Exception):
+    """Internal: agent attempted to access a path outside the bundle root."""
+
+
+def _iso(ts: float) -> str:
+    """Format a POSIX timestamp as a second-precision UTC ISO-8601 string."""
+    return datetime.fromtimestamp(ts, timezone.utc).replace(microsecond=0).isoformat()
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+
+
+class OKFBackend(BackendProtocol):
+    """A deepagents backend backed by a local OKF bundle directory.
+
+    Args:
+        root: Directory holding the OKF bundle. Created if it does not exist.
+        validate: When True, writes/edits to ``.md`` docs must be valid OKF
+            (``type`` field required) or the operation fails without touching disk.
+        auto_timestamp: When True, ``write`` sets/refreshes the ``timestamp``
+            frontmatter field on ``.md`` docs that carry frontmatter. ``edit`` never
+            rewrites the frontmatter block, so a body-only edit is byte-preserving.
+    """
+
+    def __init__(
+        self,
+        root: str | Path,
+        *,
+        validate: bool = True,
+        auto_timestamp: bool = True,
+    ) -> None:
+        self.root = Path(root).expanduser().resolve()
+        self.validate = validate
+        self.auto_timestamp = auto_timestamp
+        self.root.mkdir(parents=True, exist_ok=True)
+
+    # ------------------------------------------------------------------ helpers
+    def _resolve(self, path: str) -> Path:
+        """Resolve an agent-supplied path inside the bundle root (no escaping)."""
+        raw = str(path)
+        if "\x00" in raw:
+            raise _PathEscapeError(path)
+        try:
+            candidate = (self.root / raw.lstrip("/")).resolve()
+        except (OSError, ValueError) as exc:  # malformed path, drive on Windows, etc.
+            raise _PathEscapeError(path) from exc
+        if not self._is_contained(candidate):
+            raise _PathEscapeError(path)
+        return candidate
+
+    def _is_contained(self, p: Path) -> bool:
+        """Whether ``p`` (after symlink resolution) stays within the bundle root."""
+        try:
+            resolved = p.resolve()
+        except OSError:
+            return False
+        return resolved == self.root or self.root in resolved.parents
+
+    def _rel(self, p: Path) -> str:
+        if p == self.root:
+            return "/"
+        return "/" + p.relative_to(self.root).as_posix()
+
+    def _safe_file_info(self, p: Path) -> FileInfo | None:
+        """Build a FileInfo, or None if the entry vanished / cannot be stat'd."""
+        try:
+            stat = p.stat()
+        except OSError:
+            return None
+        return FileInfo(
+            path=self._rel(p),
+            is_dir=p.is_dir(),
+            size=stat.st_size,
+            modified_at=_iso(stat.st_mtime),
+        )
+
+    def _contained_files(self, candidates: Iterable[Path]) -> list[Path]:
+        """Filter an iterable of paths to regular files that stay within root."""
+        out: list[Path] = []
+        for p in sorted(candidates):
+            if not self._is_contained(p):
+                continue
+            try:
+                if p.is_file():
+                    out.append(p)
+            except OSError:
+                continue
+        return out
+
+    def _stamp_and_validate(self, file_path: str, content: str) -> tuple[str | None, str]:
+        """For ``write``: optionally stamp ``timestamp``, then validate OKF.
+
+        Returns ``(error, content)``; ``content`` may be re-serialized to inject the
+        timestamp. This is acceptable on a full-content write but never used by ``edit``.
+        """
+        if not is_okf_document(file_path):
+            return None, content
+        metadata, body = parse_frontmatter(content)
+        if self.auto_timestamp and metadata:
+            metadata["timestamp"] = _now_iso()
+            content = serialize_frontmatter(metadata, body)
+        if self.validate:
+            errors = validate_metadata(metadata)
+            if errors:
+                return f"OKF validation failed for {file_path}: {'; '.join(errors)}", content
+        return None, content
+
+    def _validate_only(self, file_path: str, content: str) -> str | None:
+        """For ``edit``: validate without mutating ``content``. Returns an error or None."""
+        if not is_okf_document(file_path) or not self.validate:
+            return None
+        metadata, _ = parse_frontmatter(content)
+        errors = validate_metadata(metadata)
+        if errors:
+            return f"edit would make {file_path} invalid OKF: {'; '.join(errors)}"
+        return None
+
+    # ------------------------------------------------------------------- sync API
+    def ls(self, path: str) -> LsResult:
+        try:
+            target = self._resolve(path)
+        except _PathEscapeError:
+            return LsResult(error=f"path escapes bundle root: {path}")
+        if not target.exists():
+            return LsResult(error=f"no such path: {path}")
+        if not target.is_dir():
+            return LsResult(error=f"not a directory: {path}")
+        try:
+            children = sorted(target.iterdir())
+        except OSError as exc:
+            return LsResult(error=f"cannot list {path}: {exc}")
+        entries: list[FileInfo] = []
+        for child in children:
+            if not self._is_contained(child):
+                continue
+            info = self._safe_file_info(child)
+            if info is not None:
+                entries.append(info)
+        return LsResult(entries=entries)
+
+    def read(self, file_path: str, offset: int = 0, limit: int = DEFAULT_READ_LIMIT) -> ReadResult:
+        try:
+            target = self._resolve(file_path)
+        except _PathEscapeError:
+            return ReadResult(error=f"path escapes bundle root: {file_path}")
+        if not target.is_file():
+            return ReadResult(error=f"no such file: {file_path}")
+        if offset < 0 or limit < 0:
+            return ReadResult(error="offset and limit must be non-negative")
+        try:
+            stat = target.stat()
+            text = target.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError) as exc:
+            return ReadResult(error=f"cannot read {file_path}: {exc}")
+        lines = text.splitlines(keepends=True)
+        content = "".join(lines[offset : offset + limit])
+        file_data = FileData(
+            content=content,
+            encoding="utf-8",
+            created_at=_iso(stat.st_ctime),
+            modified_at=_iso(stat.st_mtime),
+        )
+        return ReadResult(file_data=file_data)
+
+    def write(self, file_path: str, content: str) -> WriteResult:
+        try:
+            target = self._resolve(file_path)
+        except _PathEscapeError:
+            return WriteResult(error=f"path escapes bundle root: {file_path}", path=None)
+        error, content = self._stamp_and_validate(file_path, content)
+        if error:
+            return WriteResult(error=error, path=None)
+        try:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(content, encoding="utf-8")
+        except OSError as exc:
+            return WriteResult(error=f"cannot write {file_path}: {exc}", path=None)
+        return WriteResult(error=None, path=self._rel(target))
+
+    def edit(
+        self,
+        file_path: str,
+        old_string: str,
+        new_string: str,
+        replace_all: bool = False,
+    ) -> EditResult:
+        try:
+            target = self._resolve(file_path)
+        except _PathEscapeError:
+            return EditResult(
+                error=f"path escapes bundle root: {file_path}", path=None, occurrences=None
+            )
+        if not target.is_file():
+            return EditResult(error=f"no such file: {file_path}", path=None, occurrences=None)
+        try:
+            text = target.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError) as exc:
+            return EditResult(error=f"cannot read {file_path}: {exc}", path=None, occurrences=None)
+        count = text.count(old_string)
+        if count == 0:
+            return EditResult(
+                error=f"old_string not found in {file_path}", path=None, occurrences=0
+            )
+        if replace_all:
+            new_text, occurrences = text.replace(old_string, new_string), count
+        else:
+            new_text, occurrences = text.replace(old_string, new_string, 1), 1
+        # Validate the result without rewriting the frontmatter block: a body-only
+        # edit stays byte-for-byte what the agent asked for.
+        error = self._validate_only(file_path, new_text)
+        if error:
+            return EditResult(error=error, path=None, occurrences=None)
+        try:
+            target.write_text(new_text, encoding="utf-8")
+        except OSError as exc:
+            return EditResult(error=f"cannot write {file_path}: {exc}", path=None, occurrences=None)
+        return EditResult(error=None, path=self._rel(target), occurrences=occurrences)
+
+    def glob(self, pattern: str, path: str | None = None) -> GlobResult:
+        try:
+            base = self._resolve(path) if path else self.root
+        except _PathEscapeError:
+            return GlobResult(error=f"path escapes bundle root: {path}")
+        matches: list[FileInfo] = []
+        for p in self._contained_files(base.glob(pattern)):
+            info = self._safe_file_info(p)
+            if info is not None:
+                matches.append(info)
+        return GlobResult(matches=matches)
+
+    def grep(
+        self,
+        pattern: str,
+        path: str | None = None,
+        glob: str | None = None,
+    ) -> GrepResult:
+        try:
+            base = self._resolve(path) if path else self.root
+        except _PathEscapeError:
+            return GrepResult(error=f"path escapes bundle root: {path}")
+        # grep is always recursive; the optional `glob` only filters file names.
+        candidates = base.rglob(glob) if glob else base.rglob("*")
+        matches: list[GrepMatch] = []
+        for p in self._contained_files(candidates):
+            try:
+                text = p.read_text(encoding="utf-8")
+            except (OSError, UnicodeDecodeError):
+                continue
+            for lineno, line in enumerate(text.splitlines(), start=1):
+                if pattern in line:
+                    matches.append(GrepMatch(path=self._rel(p), line=lineno, text=line))
+        return GrepResult(matches=matches)
+
+    # ----------------------------------------------------------------- binary IO
+    # Raw byte transfer for non-markdown artifacts (images, exports, attachments).
+    # OKF validation is intentionally skipped here — these are opaque blobs.
+    def upload_files(self, files: list[tuple[str, bytes]]) -> list[FileUploadResponse]:
+        responses: list[FileUploadResponse] = []
+        for file_path, data in files:
+            try:
+                target = self._resolve(file_path)
+            except _PathEscapeError:
+                responses.append(FileUploadResponse(path=file_path, error="permission_denied"))
+                continue
+            try:
+                target.parent.mkdir(parents=True, exist_ok=True)
+                target.write_bytes(data)
+            except OSError as exc:
+                responses.append(FileUploadResponse(path=file_path, error=str(exc)))
+                continue
+            responses.append(FileUploadResponse(path=self._rel(target), error=None))
+        return responses
+
+    def download_files(self, paths: list[str]) -> list[FileDownloadResponse]:
+        responses: list[FileDownloadResponse] = []
+        for file_path in paths:
+            try:
+                target = self._resolve(file_path)
+            except _PathEscapeError:
+                responses.append(
+                    FileDownloadResponse(path=file_path, content=None, error="permission_denied")
+                )
+                continue
+            if not target.is_file():
+                responses.append(
+                    FileDownloadResponse(path=file_path, content=None, error="file_not_found")
+                )
+                continue
+            try:
+                data = target.read_bytes()
+            except OSError as exc:
+                responses.append(FileDownloadResponse(path=file_path, content=None, error=str(exc)))
+                continue
+            responses.append(FileDownloadResponse(path=self._rel(target), content=data, error=None))
+        return responses
+
+    # ------------------------------------------------------------------ async API
+    # Local filesystem IO is blocking; offload to a worker thread so async agents
+    # never block the event loop.
+    async def als(self, path: str) -> LsResult:
+        return await asyncio.to_thread(self.ls, path)
+
+    async def aread(
+        self, file_path: str, offset: int = 0, limit: int = DEFAULT_READ_LIMIT
+    ) -> ReadResult:
+        return await asyncio.to_thread(self.read, file_path, offset, limit)
+
+    async def awrite(self, file_path: str, content: str) -> WriteResult:
+        return await asyncio.to_thread(self.write, file_path, content)
+
+    async def aedit(
+        self,
+        file_path: str,
+        old_string: str,
+        new_string: str,
+        replace_all: bool = False,
+    ) -> EditResult:
+        return await asyncio.to_thread(self.edit, file_path, old_string, new_string, replace_all)
+
+    async def aglob(self, pattern: str, path: str | None = None) -> GlobResult:
+        return await asyncio.to_thread(self.glob, pattern, path)
+
+    async def agrep(
+        self, pattern: str, path: str | None = None, glob: str | None = None
+    ) -> GrepResult:
+        return await asyncio.to_thread(self.grep, pattern, path, glob)
+
+    async def aupload_files(self, files: list[tuple[str, bytes]]) -> list[FileUploadResponse]:
+        return await asyncio.to_thread(self.upload_files, files)
+
+    async def adownload_files(self, paths: list[str]) -> list[FileDownloadResponse]:
+        return await asyncio.to_thread(self.download_files, paths)

deepagents_okf_backend/frontmatter.py

@@ -0,0 +1,57 @@
+"""YAML frontmatter parsing/serialization for OKF markdown documents.
+
+Pure helper module — intentionally free of any ``deepagents`` import.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import yaml
+
+_DELIMITER = "---"
+
+
+def parse_frontmatter(text: str) -> tuple[dict[str, Any], str]:
+    """Split an OKF markdown document into ``(metadata, body)``.
+
+    A document has frontmatter when it starts with a ``---`` line, followed by a
+    YAML block, terminated by another ``---`` line. If there is no frontmatter,
+    ``metadata`` is an empty dict and ``body`` is the original text.
+    """
+    if not text.startswith(_DELIMITER):
+        return {}, text
+
+    lines = text.splitlines(keepends=True)
+    # lines[0] is the opening delimiter; find the closing one.
+    closing = None
+    for i in range(1, len(lines)):
+        if lines[i].strip() == _DELIMITER:
+            closing = i
+            break
+    if closing is None:
+        # Unterminated frontmatter block — treat the whole thing as body.
+        return {}, text
+
+    raw_yaml = "".join(lines[1:closing])
+    body = "".join(lines[closing + 1 :])
+    loaded = yaml.safe_load(raw_yaml) if raw_yaml.strip() else {}
+    metadata = loaded if isinstance(loaded, dict) else {}
+    return metadata, body
+
+
+def serialize_frontmatter(metadata: dict[str, Any], body: str) -> str:
+    """Render ``(metadata, body)`` back into an OKF markdown document.
+
+    When ``metadata`` is empty the body is returned unchanged (no frontmatter block).
+    """
+    if not metadata:
+        return body
+    dumped = yaml.safe_dump(metadata, sort_keys=False, allow_unicode=True).rstrip("\n")
+    return f"{_DELIMITER}\n{dumped}\n{_DELIMITER}\n{body}"
+
+
+def has_frontmatter(text: str) -> bool:
+    """Return whether ``text`` begins with a terminated frontmatter block."""
+    metadata, _ = parse_frontmatter(text)
+    return bool(metadata)

deepagents_okf_backend/okf.py

@@ -0,0 +1,64 @@
+"""Open Knowledge Format (OKF) v0.1 conventions and validation.
+
+Pure helper module — intentionally free of any ``deepagents`` import.
+
+Spec: https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+#: The only frontmatter field OKF v0.1 makes mandatory.
+REQUIRED_FIELDS: tuple[str, ...] = ("type",)
+
+#: Structured fields OKF v0.1 gives meaning to. Everything else is producer-optional.
+KNOWN_FIELDS: tuple[str, ...] = (
+    "type",
+    "title",
+    "description",
+    "resource",
+    "tags",
+    "timestamp",
+)
+
+#: Conventional per-directory index document.
+INDEX_FILENAME = "index.md"
+
+#: Extension of OKF concept documents.
+DOC_SUFFIX = ".md"
+
+
+class OKFValidationError(ValueError):
+    """Raised by strict helpers when a document violates OKF v0.1."""
+
+
+def validate_metadata(metadata: dict[str, Any]) -> list[str]:
+    """Return a list of human-readable validation errors (empty list == valid).
+
+    OKF v0.1 only requires ``type``. We additionally sanity-check the shape of a
+    couple of well-known fields so the agent cannot write a structurally broken doc.
+    """
+    errors: list[str] = []
+
+    for field in REQUIRED_FIELDS:
+        if field not in metadata or metadata[field] in (None, ""):
+            errors.append(f"missing required OKF field: '{field}'")
+
+    tags = metadata.get("tags")
+    if tags is not None and not (
+        isinstance(tags, list) and all(isinstance(t, str) for t in tags)
+    ):
+        errors.append("'tags' must be a list of strings")
+
+    for field in ("type", "title", "description", "resource", "timestamp"):
+        value = metadata.get(field)
+        if value is not None and not isinstance(value, str):
+            errors.append(f"'{field}' must be a string")
+
+    return errors
+
+
+def is_okf_document(path: str) -> bool:
+    """Whether ``path`` looks like an OKF concept document (a ``.md`` file)."""
+    return path.endswith(DOC_SUFFIX)

deepagents_okf_backend/query.py

@@ -0,0 +1,127 @@
+"""Semantic query over an OKF bundle, plus a LangChain tool factory.
+
+The six standard filesystem tools only let an agent ``grep`` raw text. OKF frontmatter
+(``type``, ``tags``, ``title``) is *structured*, so this module adds a typed query on top
+and exposes it as an optional LangChain tool the agent can call directly — kept separate so
+``OKFBackend`` itself stays a pure ``BackendProtocol`` implementation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from langchain_core.tools import BaseTool, tool
+
+from .backend import OKFBackend
+from .frontmatter import parse_frontmatter
+
+
+@dataclass
+class OKFHit:
+    """A single OKF document matched by :func:`query_bundle`."""
+
+    path: str
+    type: str | None = None
+    title: str | None = None
+    description: str | None = None
+    tags: list[str] = field(default_factory=list)
+
+
+def query_bundle(
+    backend: OKFBackend,
+    *,
+    type: str | None = None,
+    tags: list[str] | None = None,
+    title_contains: str | None = None,
+) -> list[OKFHit]:
+    """Return OKF documents whose frontmatter matches every supplied filter.
+
+    Filters are ANDed. ``tags`` matches when the document carries *all* given tags.
+    ``type`` matches case-insensitively; ``title_contains`` is a case-insensitive substring.
+    """
+    glob_result = backend.glob("**/*.md")
+    if glob_result.error or not glob_result.matches:
+        return []
+
+    wanted_tags = {t.lower() for t in (tags or [])}
+    hits: list[OKFHit] = []
+    for entry in glob_result.matches:
+        read_result = backend.read(entry["path"])
+        if read_result.error or read_result.file_data is None:
+            continue
+        metadata, _ = parse_frontmatter(read_result.file_data["content"])
+        if not metadata:
+            continue
+
+        doc_type = metadata.get("type")
+        if type is not None and (doc_type or "").lower() != type.lower():
+            continue
+
+        raw_tags = metadata.get("tags") or []
+        # A malformed bundle may store `tags` as a bare string; normalize to a list
+        # so we never iterate it character-by-character.
+        doc_tags = raw_tags if isinstance(raw_tags, list) else [raw_tags]
+        if wanted_tags and not wanted_tags.issubset({str(t).lower() for t in doc_tags}):
+            continue
+
+        doc_title = metadata.get("title")
+        if title_contains is not None and title_contains.lower() not in (doc_title or "").lower():
+            continue
+
+        hits.append(
+            OKFHit(
+                path=entry["path"],
+                type=doc_type,
+                title=doc_title,
+                description=metadata.get("description"),
+                tags=[str(t) for t in doc_tags],
+            )
+        )
+    return hits
+
+
+def _format_hits(hits: list[OKFHit]) -> str:
+    if not hits:
+        return "No matching OKF documents found."
+    lines = [f"Found {len(hits)} document(s):"]
+    for h in hits:
+        parts = [f"- {h.path}"]
+        if h.type:
+            parts.append(f"[{h.type}]")
+        if h.title:
+            parts.append(h.title)
+        line = " ".join(parts)
+        if h.description:
+            line += f" — {h.description}"
+        if h.tags:
+            line += f" (tags: {', '.join(h.tags)})"
+        lines.append(line)
+    return "\n".join(lines)
+
+
+def make_okf_query_tool(backend: OKFBackend) -> BaseTool:
+    """Build a LangChain tool that lets an agent query the OKF bundle by frontmatter.
+
+    Add the returned tool to ``create_deep_agent(tools=[...])`` so the agent can do
+    structured lookups (by ``type``/``tags``/``title``) instead of blind ``grep``.
+    """
+
+    @tool
+    def okf_query(
+        type: str | None = None,
+        tags: list[str] | None = None,
+        title_contains: str | None = None,
+    ) -> str:
+        """Search the OKF knowledge bundle by frontmatter fields.
+
+        Args:
+            type: Match documents whose ``type`` equals this (case-insensitive),
+                e.g. "BigQuery Table" or "Metric".
+            tags: Match documents carrying all of these tags.
+            title_contains: Match documents whose title contains this substring.
+        """
+        return _format_hits(
+            query_bundle(backend, type=type, tags=tags, title_contains=title_contains)
+        )
+
+    return okf_query

deepagents_okf_backend-0.1.0.dist-info/METADATA

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: deepagents-okf-backend
+Version: 0.1.0
+Summary: OKF-aware virtual filesystem backend for LangChain Deep Agents (Open Knowledge Format).
+Project-URL: Homepage, https://github.com/emanueleielo/deepagents-okf-backend
+Project-URL: Repository, https://github.com/emanueleielo/deepagents-okf-backend
+Project-URL: Issues, https://github.com/emanueleielo/deepagents-okf-backend/issues
+Project-URL: OKF spec, https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing
+Author-email: Emanuele Ielo <emanueleielo@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: agent,backend,deepagents,langchain,llm,okf,open-knowledge-format
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: deepagents>=0.6
+Requires-Dist: langchain-core>=0.3
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Provides-Extra: examples
+Requires-Dist: langchain-anthropic>=0.3; extra == 'examples'
+Requires-Dist: python-dotenv>=1.0; extra == 'examples'
+Description-Content-Type: text/markdown
+
+# deepagents-okf-backend
+
+[![CI](https://github.com/emanueleielo/deepagents-okf-backend/actions/workflows/ci.yml/badge.svg)](https://github.com/emanueleielo/deepagents-okf-backend/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/deepagents-okf-backend.svg)](https://pypi.org/project/deepagents-okf-backend/)
+[![Python](https://img.shields.io/pypi/pyversions/deepagents-okf-backend.svg)](https://pypi.org/project/deepagents-okf-backend/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+An **OKF-aware virtual filesystem backend** for [LangChain Deep Agents](https://docs.langchain.com/oss/python/deepagents/overview).
+
+It mounts an [Open Knowledge Format (OKF)](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing)
+bundle — *"a directory of markdown files with YAML frontmatter"* — as the agent's filesystem,
+so a deep agent can **read, search, and curate** organizational knowledge while every write
+stays a **valid OKF document**.
+
+> 🧩 Community backend (not maintained by LangChain), built for the
+> [`integrations/backends`](https://docs.langchain.com/oss/python/integrations/backends) list.
+
+## Why
+
+A deep agent's knowledge memory is usually either **ephemeral** (`StateBackend`) or **closed**
+(`ContextHubBackend` → LangSmith Hub). OKF is the **open, vendor-neutral** alternative:
+git-versionable markdown, human-readable, parseable by any agent or framework.
+
+| | `StateBackend` | `StoreBackend` | `FilesystemBackend` | **`OKFBackend`** |
+|---|---|---|---|---|
+| Persists across threads | ❌ | ✅ | ✅ | ✅ |
+| Human-readable on disk | ❌ | ❌ | ✅ | ✅ |
+| Vendor-neutral / portable bundle | ❌ | ❌ | ➖ | ✅ |
+| Structured frontmatter query | ❌ | ❌ | ❌ | ✅ |
+| Validates writes as a shareable format | ❌ | ❌ | ❌ | ✅ |
+
+What `OKFBackend` adds:
+
+- **Open knowledge, no lock-in** — portable markdown bundles, not a proprietary store.
+- **Semantic, not blind** — query by `type` / `tags` / `title`, not just `grep`.
+- **Self-improving wiki** — the agent maintains the bundle; writes are validated as OKF.
+- **Cross-agent sharing** — *"a bundle synthesized by one LLM can be queried by another."*
+- **Sync + async**, path-sandboxed to the bundle root, fully typed (`py.typed`).
+
+## Install
+
+```bash
+pip install deepagents-okf-backend
+```
+
+## Quickstart
+
+```python
+from deepagents import create_deep_agent
+from deepagents_okf_backend import OKFBackend
+
+backend = OKFBackend("./knowledge", validate=True, auto_timestamp=True)
+
+agent = create_deep_agent(
+    tools=[],
+    instructions="You curate the organization's OKF knowledge bundle.",
+    backend=backend,
+)
+```
+
+### Knowledge surface + scratch space (`CompositeBackend`)
+
+Mount the OKF bundle on `/knowledge` and keep an ephemeral scratch filesystem on `/`:
+
+```python
+from deepagents.backends import CompositeBackend, StateBackend
+from deepagents_okf_backend import OKFBackend
+
+backend = CompositeBackend(
+    routes={"/knowledge": OKFBackend("./knowledge")},
+    default=StateBackend(),
+)
+```
+
+### Structured query tool
+
+The six standard filesystem tools only `grep` raw text. Give the agent a typed lookup over
+OKF frontmatter:
+
+```python
+from deepagents import create_deep_agent
+from deepagents_okf_backend import OKFBackend, make_okf_query_tool
+
+backend = OKFBackend("./knowledge")
+agent = create_deep_agent(
+    tools=[make_okf_query_tool(backend)],   # okf_query(type=..., tags=..., title_contains=...)
+    instructions="Use okf_query to find tables and metrics before answering.",
+    backend=backend,
+)
+```
+
+You can also call it directly:
+
+```python
+from deepagents_okf_backend import query_bundle
+
+hits = query_bundle(backend, type="Metric", tags=["growth"])
+```
+
+## What is OKF?
+
+Open Knowledge Format (Google Cloud, 2026) represents knowledge as a directory of markdown
+files with YAML frontmatter. The only required field is `type`; `title`, `description`,
+`resource`, `tags`, and `timestamp` are optional. See the
+[announcement](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing).
+
+```markdown
+---
+type: BigQuery Table
+title: Orders
+description: One row per completed customer order.
+tags: [sales, revenue]
+---
+# Schema
+| Column | Type | Description |
+|--------|------|-------------|
+| `order_id` | STRING | Globally unique order identifier. |
+```
+
+## Development
+
+See [`DEVELOPMENT_PLAN.md`](DEVELOPMENT_PLAN.md). Contributions welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+```bash
+pip install -e ".[dev]"
+ruff check . && mypy src && pytest --cov=deepagents_okf_backend
+```
+
+## License
+
+MIT © Emanuele Ielo

deepagents_okf_backend-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+deepagents_okf_backend/__init__.py,sha256=RWzcWJR2Aqjb5HCw4pTjtTLzx13jxkIkxm_ql1GfBd4,563
+deepagents_okf_backend/backend.py,sha256=A0oNId_v0dNkpfW5YaY-Yw4z7yfKCpsymaWs_IWIr8Y,15396
+deepagents_okf_backend/frontmatter.py,sha256=9R79Bn85xcFRvzA2yFZ9WQjL85XvmaSk5niOKEqCN0w,1892
+deepagents_okf_backend/okf.py,sha256=6qTQdrtld7j8NBFvDyn48zIUX2bIs6xO1IZLgH1ELzE,2005
+deepagents_okf_backend/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+deepagents_okf_backend/query.py,sha256=akWXe_xcZvxsoweoNVd9K_g0xnGW-Uy0fQLfK6-1x4g,4300
+deepagents_okf_backend-0.1.0.dist-info/METADATA,sha256=_oRJeU07RlegnHY2xSySzNX8FkOQPdcv2MZgZ47wleI,6543
+deepagents_okf_backend-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+deepagents_okf_backend-0.1.0.dist-info/licenses/LICENSE,sha256=LIAri2meHjPOuxPFxppzOk7HMUM3-sws8re8HioDyOo,1070
+deepagents_okf_backend-0.1.0.dist-info/RECORD,,

deepagents_okf_backend-0.1.0.dist-info/WHEEL

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

deepagents_okf_backend-0.1.0.dist-info/licenses/LICENSE

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