Repository navigation
Conversation
Expose a directory of typed markdown knowledge (Open Knowledge Format v0.2) to an agent progressively: frontmatter index (L1), one concept body (L2), its attached resources (L3), and a deterministic offline search. Trust tier, lifecycle, and staleness are derived from frontmatter on every read and used only to filter discovery. A bundle is untrusted input. Concept bodies and resource text are labelled as data, never instructions; every path argument resolves through one bundle-root guard that refuses `..` traversal and symlink escape at load time as well as at call time; and no tool raises, so a hostile or broken bundle reaches the model as a structured error dict instead of an opaque failure. 107 tests, including an adversarial suite and golden tests over the four published OKF sample bundles.
05b41f6 to
3f4c4f5
Compare
|
Refreshed onto current The conflict was purely positional: Re-ran the suite after the rebase: No functional changes; the rebase is clean against |
|
@wukath — Local evidence is in the description: |
Problem
ADK has first-class support for procedural knowledge (
SKILL.mdtrees) but no way to consume a local directory of declarative knowledge: markdown concepts with YAML frontmatter carryingtype,tags,sources, verification events,status, andstale_after. An agent grounded in such a corpus has to either load all of it into context or grow a bespoke retrieval layer that discards the structure the corpus already carries.Solution
google.adk.integrations.okf.OkfToolsetreads an OKF v0.2 bundle as progressive, filterable context:okf_indexokf_readokf_resourceokf_searchIt lives under
integrations/because that is what the directory's README describes: a self-contained sub-package that manages its own internal structure and keeps optional third-party dependencies out of core. This one needs none — it reads frontmatter withpyyaml, which is already a core dependency, so no extra and no lazy third-party import are involved.Design points worth reviewing:
okf_indexandokf_search(directory,type,tags,trust_tier,include_deprecated,include_stale), so the two tools cannot disagree about which concepts exist.statusreads asstable— OKF §11 forbids rejecting a concept for an unrecognised value — and astale_afterwithout a timezone is treated as absent rather than guessed./is bundle-relative, never host-absolute...traversal and symlinks escaping the bundle root are refused by one guard used by every path argument, at eager load as well as at call time.not_found,unsafe_path,invalid_argument,unreadable,invalid_regex,internal_errorcome back as structured dicts, and a malformed bundle is reported as aviolationslist rather than aborting the load.Security
A bundle is untrusted input, written by whoever produced the corpus rather than by the agent's operator.
content_is_untrusted_data: true.Testing Plan
Unit tests — new directory, no existing test changed:
fixtures/bundles/PROVENANCE.md): §11 rules 1–3, exact concept counts, derived trust tiers, and tolerance of a producer-extension key that the spec forbids rejecting.Manual E2E —
test_agent_smoke.pyruns anAgentwithMockModelthroughInMemoryRunner: the model callsokf_read, the tool result carries the concept's frontmatter and body, and the run completes. This needs no network and no model credentials, so it can be read as the end-to-end evidence for the tool wiring:Repo gates —
pre-commit run --files <changed>passes every hook on this diff:ruff,isort,pyink,addlicense,check-new-py-prefix(private modules with exported symbols), the unit-guide check, compliance,check-docs, andcodespell.Checklist
docs/guides/integrations/okf/toolset/index.md, listed indocs/guides/README.mdsrc/google/adk/integrations/okf/README.md