deepagents-okf-backend 0.1.0__tar.gz

deepagents_okf_backend-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,26 @@
+name: Bug report
+description: Report a problem with deepagents-okf-backend
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear description of the bug and what you expected instead.
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: Smallest code snippet that reproduces the issue.
+      render: python
+    validations:
+      required: true
+  - type: input
+    id: versions
+    attributes:
+      label: Versions
+      description: Output of `pip show deepagents-okf-backend deepagents | grep Version` and your Python version.
+    validations:
+      required: true

deepagents_okf_backend-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Deep Agents docs
+    url: https://docs.langchain.com/oss/python/deepagents/backends
+    about: How backends work in LangChain Deep Agents.
+  - name: Open Knowledge Format (OKF)
+    url: https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing
+    about: The OKF specification this backend targets.

deepagents_okf_backend-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,18 @@
+name: Feature request
+description: Suggest an idea for deepagents-okf-backend
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What are you trying to do that is hard or impossible today?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: How could the backend or OKF integration solve it?
+    validations:
+      required: true

deepagents_okf_backend-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,11 @@
+## Summary
+
+<!-- What does this PR change and why? -->
+
+## Checklist
+
+- [ ] `ruff check .` passes
+- [ ] `mypy src` passes
+- [ ] `pytest` passes (added/updated tests for the change)
+- [ ] Backend methods still return result types with `error` set — they never raise
+- [ ] Updated `CHANGELOG.md` if user-facing

deepagents_okf_backend-0.1.0/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      python-deps:
+        patterns: ["*"]
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

deepagents_okf_backend-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Type check
+        run: mypy src
+      - name: Test
+        run: pytest -q --cov=deepagents_okf_backend --cov-report=term-missing --cov-fail-under=85

deepagents_okf_backend-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,26 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # PyPI Trusted Publishing (OIDC), no API token needed
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

deepagents_okf_backend-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store
+
+# Internal working docs — kept local, not published
+/DEVELOPMENT_PLAN.md
+/CHANGELOG.md

deepagents_okf_backend-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,56 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes
+- Focusing on what is best for the overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards and
+will take appropriate and fair corrective action in response to any behavior
+that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the maintainers at **emanueleielo@gmail.com**. All complaints will
+be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+[homepage]: https://www.contributor-covenant.org

deepagents_okf_backend-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing
+
+Thanks for helping improve `deepagents-okf-backend`!
+
+## Setup
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Checks (must pass before a PR)
+
+```bash
+ruff check .
+mypy src
+pytest
+```
+
+## Guidelines
+
+- **Never raise from backend methods.** Return the appropriate result type with `error` set
+  (this is the `BackendProtocol` contract).
+- Keep `frontmatter.py` and `okf.py` free of `deepagents` imports — they are pure helpers and
+  the bulk of the test coverage lives there.
+- Add/extend tests under `tests/` for any behavior change; keep the sample bundle in
+  `tests/fixtures/sample_bundle/` a **valid** OKF bundle.
+- Match the existing code style; imports go at the top of the file.
+
+## Releasing
+
+1. Bump `version` in `pyproject.toml` and update `CHANGELOG.md`.
+2. Tag `vX.Y.Z`, push, let CI build.
+3. Publish to PyPI, create a GitHub release.
+4. Open a PR to the LangChain docs repo adding a row to the `integrations/backends` table.

deepagents_okf_backend-0.1.0/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.

deepagents_okf_backend-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,132 @@
+# 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/SECURITY.md

@@ -0,0 +1,25 @@
+# Security Policy
+
+## Supported Versions
+
+The latest released `0.x` version receives security fixes. This project is
+pre-1.0 and the API may change between minor versions.
+
+## Reporting a Vulnerability
+
+Please **do not** open a public issue for security problems.
+
+Instead, use GitHub's [private vulnerability reporting](https://github.com/emanueleielo/deepagents-okf-backend/security/advisories/new)
+or email **emanueleielo@gmail.com**. You can expect an initial response within a
+few days.
+
+## Security notes for this backend
+
+`OKFBackend` reads and writes **real files** under the directory you pass as `root`.
+
+- The backend sandboxes all agent-supplied paths to `root` (path traversal such as
+  `../` is rejected). This is covered by tests.
+- Still, point `root` at a **dedicated bundle directory**, never at a path that
+  contains secrets, credentials, or system files. An agent with write access to a
+  shared directory can modify anything inside it.
+- For untrusted/hostile workloads prefer an isolated sandbox backend.

deepagents_okf_backend-0.1.0/examples/composite_knowledge.py

@@ -0,0 +1,36 @@
+"""Knowledge surface + scratch space, with a structured OKF query tool.
+
+The agent reads/curates an OKF bundle on ``/knowledge`` (durable, validated) while using an
+ephemeral ``StateBackend`` for everything else, and can look documents up by frontmatter.
+
+Run:  python examples/composite_knowledge.py
+"""
+
+from __future__ import annotations
+
+from deepagents import create_deep_agent
+from deepagents.backends import CompositeBackend, StateBackend
+
+from deepagents_okf_backend import OKFBackend, make_okf_query_tool
+
+
+def build_agent():  # type: ignore[no-untyped-def]
+    okf = OKFBackend("./knowledge", validate=True, auto_timestamp=True)
+    backend = CompositeBackend(
+        routes={"/knowledge": okf},
+        default=StateBackend(),
+    )
+    return create_deep_agent(
+        tools=[make_okf_query_tool(okf)],
+        instructions=(
+            "Knowledge lives under /knowledge as an OKF bundle. "
+            "Use okf_query to find tables/metrics before answering, and keep scratch notes "
+            "elsewhere."
+        ),
+        backend=backend,
+    )
+
+
+if __name__ == "__main__":
+    agent = build_agent()
+    print("Agent ready with OKF knowledge surface on /knowledge")

deepagents_okf_backend-0.1.0/examples/quickstart.py

@@ -0,0 +1,39 @@
+"""Minimal example: mount an OKF bundle as a deep agent's filesystem.
+
+Run:  python examples/quickstart.py
+(Requires `pip install deepagents-okf-backend` and a model configured for deepagents.)
+"""
+
+from __future__ import annotations
+
+from deepagents_okf_backend import OKFBackend
+
+
+def main() -> None:
+    backend = OKFBackend("./knowledge", validate=True, auto_timestamp=True)
+
+    # Write a valid OKF document directly through the backend.
+    doc = """---
+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. |
+"""
+    result = backend.write("/tables/orders.md", doc)
+    print("write ->", result)
+
+    print("read ->", backend.read("/tables/orders.md").file_data["content"][:60], "...")
+    print("grep ->", backend.grep("revenue"))
+
+    # An invalid OKF doc (no `type`) is rejected without touching disk.
+    bad = backend.write("/tables/broken.md", "# no frontmatter here")
+    print("invalid write ->", bad.error)
+
+
+if __name__ == "__main__":
+    main()