ExOKF.Context (ex_okf v0.1.0)

Copy Markdown View Source

Provenance-aware AI context assembly.

Walks the concept graph outward from a seed concept, ranks neighbors, respects a token budget, deduplicates content, and records a traversal explanation suitable for citations in agent prompts.

Ranking and deeper provenance features continue to expand in v0.3.

Fields (t/0)

FieldTypeDescription
seedString.t()Starting concept id, e.g. "tables/orders".
chunks[t:chunk/0]Ordered content chunks packed into the budget.
tokens_usednon_neg_integer()Approximate tokens consumed by chunks.
token_budgetpos_integer() | :infinityBudget passed to build/3.
traversal[map()]Steps %{concept_id, depth, score} explaining ranking.
truncatedboolean()true when the budget stopped packing early.

Example

%ExOKF.Context{
  seed: "tables/orders",
  chunks: [
    %{
      concept_id: "tables/orders",
      title: "Orders",
      type: "BigQuery Table",
      body: "# Schema\n...",
      depth: 0,
      tokens: 120,
      citations: ["https://console.cloud.google.com/bigquery?..."]
    }
  ],
  tokens_used: 120,
  token_budget: 4000,
  traversal: [%{concept_id: "tables/orders", depth: 0, score: 1.0}],
  truncated: false
}

Summary

Types

chunk()

A single packed context chunk.

option()

Options for build/3.

t()

Assembled context result.

Functions

build(bundle, concept_id, opts \\ [])

Assembles context around concept_id.

to_prompt(ctx)

Renders assembled context as a single markdown prompt block.

Types

chunk()

@type chunk() :: %{
  concept_id: String.t(),
  title: String.t(),
  type: String.t() | nil,
  body: String.t(),
  depth: non_neg_integer(),
  tokens: non_neg_integer(),
  citations: [String.t()]
}

A single packed context chunk.

  • :concept_id (String.t()) — source concept id
  • :title (String.t()) — display title
  • :type (String.t() \| nil) — OKF type
  • :body (String.t()) — markdown body (may be truncated)
  • :depth (non_neg_integer()) — graph hops from the seed (0 = seed)
  • :tokens (non_neg_integer()) — estimated token count for this chunk
  • :citations ([String.t()]) — resource URL plus external link targets

option()

@type option() ::
  {:depth, non_neg_integer()}
  | {:token_budget, pos_integer() | :infinity}
  | {:include_seed, boolean()}
  | {:chars_per_token, pos_integer()}

Options for build/3.

  • {:depth, non_neg_integer()} — max graph hops (default 2)

  • {:token_budget, pos_integer() | :infinity} — approximate token limit

  • {:include_seed, boolean()} — include the seed concept (default true)
  • {:chars_per_token, pos_integer()} — heuristic divisor (default 4)

t()

@type t() :: %ExOKF.Context{
  chunks: [chunk()],
  seed: String.t(),
  token_budget: pos_integer() | :infinity,
  tokens_used: non_neg_integer(),
  traversal: [map()],
  truncated: boolean()
}

Assembled context result.

See the module documentation for field meanings.

Functions

build(bundle, concept_id, opts \\ [])

@spec build(ExOKF.Bundle.t(), String.t(), [option()]) :: {:ok, t()} | {:error, term()}

Assembles context around concept_id.

Parameters

  • bundle (ExOKF.Bundle.t()) — loaded OKF bundle
  • concept_id (String.t()) — seed concept id
  • opts ([t:option/0]) — assembly options (see option/0)

Returns

  • {:ok, t()} — assembled context
  • {:error, {:unknown_concept, String.t()}} — seed id not in the bundle

Examples

iex> bundle = ExOKF.TestSupport.sample_bundle()
iex> {:ok, ctx} = ExOKF.Context.build(bundle, "tables/orders", depth: 1, token_budget: 5000)
iex> ctx.seed
"tables/orders"
iex> hd(ctx.chunks).concept_id
"tables/orders"

to_prompt(ctx)

@spec to_prompt(t()) :: String.t()

Renders assembled context as a single markdown prompt block.

Includes per-chunk headings, optional citation lines, and a traversal appendix when steps were recorded.

Parameters

Examples

iex> bundle = ExOKF.TestSupport.sample_bundle()
iex> {:ok, ctx} = ExOKF.Context.build(bundle, "tables/orders", depth: 0)
iex> prompt = ExOKF.Context.to_prompt(ctx)
iex> prompt =~ "tables/orders"
true