Exactly. That difference is intentional and quite important. The common directories represent the core OKF knowledge model, while the additional metrics / computations / policies / skills / attesters directories in acme_retail demonstrate a much more operational, governed, executable knowledge system.
The Acme Retail bundle is essentially showing how OKF can move beyond "documentation of data" toward trusted business intelligence that an agent can execute and verify.
Think of the bundles in two layers
Directory Purpose Typical role
datasets/ Describes datasets What data exists?
tables/ Describes BigQuery tables What does each table contain?
references/ Relationships/cross-references How are concepts connected?
metrics/ Business definitions What exactly does "Revenue" mean?
computations/ Approved SQL How should Revenue be calculated?
policies/ Business/Finance rules What rules govern the calculation?
skills/ Agent execution instructions How should an agent perform the calculation?
attesters/ Deterministic verification How do we verify the result?
The first three tell an agent what the data is.
The Acme-specific extensions tell an agent what the business means, how to calculate it, what rules apply, how to execute it, and how to verify the result.
OKF Bundle
│
┌─────────────┴─────────────┐
│ │
Knowledge Layer Execution Layer
│ │
▼ ▼
datasets metrics
tables computations
references policies
│
▼
skills
│
▼
attesters
The first three tell an agent what the data is.
The Acme-specific extensions tell an agent what the business means, how to calculate it, what rules apply, how to execute it, and how to verify the result.
Why metrics is particularly interesting
Suppose Acme Retail asks:
"What was our net revenue last quarter?"
A normal RAG system might retrieve documents containing:
Net Revenue = Revenue - Discounts - Returns
and then ask the LLM to figure out what to do.
Acme's OKF approach can instead have a formal metric:
metrics/
net_revenue.md
which establishes the business definition.
Then:
net_revenue
│
▼
computation
│
▼
approved SQL
│
▼
BigQuery
This is a major distinction.
The LLM isn't being asked:
"Write some SQL that you think calculates net revenue."
It can be told:
"The organization has already defined and sanctioned how Net Revenue is calculated. Execute that computation."
computations is the next important piece
This is where OKF starts looking like executable knowledge.
For example, conceptually:
metrics/net_revenue.md
│
│ defines
▼
computations/net_revenue.sql
│
│ executes against
▼
tables/orders
tables/refunds
tables/discounts
The computation is sanctioned SQL, rather than dynamically generated SQL.
That gives you a much stronger governance model.
Instead of:
User
↓
LLM
↓
Generate SQL
↓
Database
you have:
User
↓
Agent
↓
Identify metric
↓
Find sanctioned computation
↓
Execute computation
↓
Verify receipt
↓
Answer
policies adds the business governance
This is another very interesting part.
Imagine Finance has a policy saying:
Revenue must exclude cancelled orders and recognized revenue must follow a particular accounting rule.
That policy becomes part of the knowledge bundle.
So now the chain can be:
Finance Policy
│
▼
Metric Definition
│
▼
Sanctioned Computation
│
▼
Execution
This is much stronger than simply putting the Finance policy into a vector database and hoping the LLM retrieves it.
skills is where agents come in
This is probably the directory I'd pay the most attention to if you're looking at OKF from an Agent/RAG architecture perspective.
A skill describes how an executor should perform an operation.
Conceptually:
skills/
calculate_net_revenue.md
could tell an agent something along the lines of:
1. Identify the requested metric.
2. Load the corresponding Attested Computation.
3. Execute against the approved data source.
4. Produce a computation receipt.
5. Pass the receipt to the attester.
6. Only return the result after verification.
So the OKF bundle isn't merely providing information.
It's providing knowledge + instructions + executable artifacts + verification.
And attesters closes the loop
This is the really interesting architecture.
Imagine the computation produces:
Result:
Net Revenue = $12,481,235
You don't necessarily want the LLM to simply say:
"The calculation looks correct."
Instead, an attester can deterministically verify the computation receipt.
So:
┌───────────────┐
│ Metric │
└───────┬───────┘
│
▼
┌───────────────┐
│ Computation │
└───────┬───────┘
│
▼
┌───────────┐
│ BigQuery │
└─────┬─────┘
│
▼
Computation Receipt
│
▼
┌───────────────┐
│ Attester │
└───────┬───────┘
│
┌─────┴─────┐
│ │
VALID INVALID
│
▼
Agent
│
▼
User
That's a very different philosophy from conventional RAG.
This is why Acme Retail is a particularly good example
I would categorize the repository examples roughly like this:
Basic OKF bundles
──────────────────
datasets
+
tables
+
references
↓
"Understand my data"
whereas:
Acme Retail
──────────────────────────────
datasets
tables
references
+
metrics
computations
policies
skills
attesters
↓
"Understand my business,
execute approved operations,
and prove the result"
That is the part I'd explore if you're evaluating OKF seriously.
It isn't necessarily a replacement for GraphRAG, vector RAG, or a knowledge graph. Rather, it can provide a structured, governed knowledge layer on top of which those systems and agents can operate.
And the Acme Retail example is essentially the repository's demonstration of that idea: "Don't just retrieve knowledge—define what is authoritative, executable, and verifiable."
No comments:
Post a Comment