Skip to content

OKF4net 0.3.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 29 Jul 11:02
v0.3.0
81ebdb9

OKF4net now targets OKF specification v0.2. The core library and okf CLI
implement v0.2's provenance, trust, and lifecycle model, with the two
v0.2-sanctioned legacy fallbacks so v0.1 bundles keep loading unchanged.
OKF4net.Catalog gains fully-implemented session/tenant memory tiers and
three selectable knowledge-resolver ranking strategies.

Added

  • Provenance / trust / lifecycle frontmatter (§5) — typed, order-preserving
    accessors on Frontmatter, each projected lazily and never throwing on
    malformed input (permissive loading, §3):
    • sources with per-entry credibility signals (author, usage_count,
      last_modified) and the usage_window sibling (Source, UsageWindow).
    • generated / verified stamps and the derived trust tier (Stamp,
      TrustTier: unverified / machine-confirmed / human-reviewed).
    • status (draft|stable|deprecated) and stale_after (Lifecycle,
      ConceptStatus), with staleness computed against an injectable IOkfClock.
    • The §7 actor convention (Actor: human:/process:/<producer>/<version>).
    • StalePolicy (Use / Tolerate / Strict) for consumers.
  • OkfDocument.Sources() — v0.2 provenance with the §13.1 legacy fallback:
    the frontmatter sources field, or the legacy # Citations body list when it
    is absent. Frontmatter.LastChangedAt falls back generated.at ?? timestamp.
  • v0.2 conformance fixture (tests/fixtures/okf_v02) and its byte-exact golden.
  • Consumer-layer v0.2 wiring — the provenance/trust/lifecycle model is now
    surfaced through OKF4net.Agents and OKF4net.Catalog:
    • okf_write_concept auto-stamps a generated block (§5.2) —
      {by: okf4net/<version>, at: <UTC>} — when the frontmatter has none (opt-in
      per tool; the scoped-memory write path is deliberately never auto-stamped).
    • okf_read_concept prints a status | trust | stale meta line, and
      okf_search marks hits [deprecated] / [stale], when those differ from
      the defaults.
    • OkfContextProvider, GroupedKnowledgeResolver, and KnowledgeQuery honor
      a StalePolicy (default Use — surface everything, never silently drop)
      when admitting concepts, with staleness resolved against an injectable clock.
    • KnowledgePassage carries the matching concept's TrustTier and full
      Lifecycle, so a resolver or host can filter and render provenance without
      reparsing frontmatter.
  • Session and tenant memory tiers are now fully implemented and tested.
    v0.2.0 shipped only the user tier working end-to-end (session/tenant were
    contract/parse-only). The underlying mechanism (FileMemoryStore, manifest
    parsing, DI wiring, OkfContextProviderOptions.CaptureTier) turned out to
    already be generic across all three tiers, so this release is primarily the
    test coverage, one path-nesting fix (see Fixed), and doc corrections that
    make the existing generic mechanism trustworthy for session/tenant, not new
    surface area.
  • Selectable resolver ranking strategies. IKnowledgeResolver searches
    can now be ranked three ways: GroupedBySource (each source's results
    concatenated in priority order — the previous and still-default
    behaviour), Merged (one cross-source ranking by descending score, with
    source priority as a tie-break only), and PriorityWeighted (source
    priority first, score only within a priority tier). Choose one per host
    via KnowledgeOptions.DefaultResolverStrategy, or per call via
    KnowledgeQuery.ResolverStrategy. AddKnowledge now registers
    KnowledgeResolverRouter as the IKnowledgeResolver, so existing
    consumers gain per-query selection without any code change, and result
    ordering is unchanged until a host opts in.
  • Fairness interleaving for fused strategies. An optional
    FairnessQuota (host-level KnowledgeOptions.DefaultFairnessQuota or
    per-query KnowledgeQuery.FairnessQuota) caps how many consecutive
    passages one source may contribute before another source's next-best
    passage is pulled ahead. It reorders only — no passage is ever dropped —
    so it affects consumers that truncate early, such as an agent context
    provider spending a token budget top-down.
  • Same-directory source dedup. The merged strategies collapse two
    enabled manifest entries that resolve to the same directory, searching
    that bundle once instead of twice. Two different directories that
    happen to share a concept id are never merged: a concept id is relative
    to its own bundle root and is not a globally stable identity.
  • OkfContextProviderOptions.KnowledgeQueryFairnessQuota — attaches a
    fairness quota to the knowledge query the context provider issues. The
    provider is the archetypal early-truncating consumer (it renders
    passages top-down until its token budget is spent), so this is what lets
    a budget-bounded agent see several sources instead of one prolific
    source's entire run.

Changed

  • OkfSpec.Version is now "0.2" — okf validate and -V report OKF v0.2.
    Conformance (§11) still requires only a non-empty type, a parseable
    frontmatter block, and well-formed reserved files; every new
    provenance/trust/lifecycle/actor check is a Warning or Info, never an Error.
  • BundleValidator emits the v0.2 soft-guidance diagnostics and takes an
    optional IOkfClock for deterministic staleness.
  • The producer-side OkfDocument.Validate() now requires type/title/
    description (no longer timestamp).
  • Breaking: DefaultKnowledgeResolver is renamed GroupedKnowledgeResolver
    (behaviour identical). Code that resolves IKnowledgeResolver from DI is
    unaffected; only direct references to the concrete type name need
    updating.
  • A non-positive FairnessQuota is rejected with an ArgumentException
    by every strategy — including GroupedBySource, which ignores the quota
    otherwise — so the same malformed query fails the same way whichever
    strategy runs it. A non-positive resolver constructor default throws
    ArgumentOutOfRangeException at construction. null remains the way to
    disable fairness reordering.

Fixed

  • YAML flow-style plain scalars now keep bare colons inside values, so v0.2
    frontmatter written in flow style (generated: { by: human:ada, at: … },
    URLs, ISO timestamps) parses correctly.
  • MemoryPath.For's session-tier path now nests under tenant and user
    (memory-session/<tenant>/<user>/<session>, matching how the user tier
    already nests under tenant), closing an isolation gap where two different
    tenants sharing the same session id would have collided on
    memory-session/<session>. Any deployment that had already enabled the
    session tier (undocumented and untested before this release) will need to
    re-capture session memory under the new path -- existing session-tier
    content at the old path is orphaned, not migrated.
dotnet add package OKF4net --version 0.3.0

Full changelog: https://github.com/jchable/okf4net/blob/main/CHANGELOG.md#030---2026-07-29

Assets 8
Loading