Closing the Gaps

01 Executive summary

Two axes, one direction of travel.

The gap analysis found that Context Graph (CG) meets or exceeds the article on the decision-memory / provenance / temporal axis — that is exactly what the 11-field RelationContext (rc) was built for — and is solid on multi-hop retrieval (CGR3). What CG lacks is the article’s other half: the ontology as an operational runtime — typed schema, executable actions, constraint enforcement, inference, and object-level access control.

This document proposes closing that half in priority order. The headline move (P1) is a Business Rules Engine: it directly fills the largest, most concrete gaps — constraint enforcement and the first useful slice of an action layer — while staying close to CG’s grain. Because authoring rule logic by hand is the adoption bottleneck, we pair it with an AI agent that generates the rule DSL from natural-language policy, per use case. P2 (Ontology) then gives those rules a typed vocabulary to reference. P3 captures the remaining gaps so nothing is lost.

02 Gap scorecard

Where we stand against the article’s claimed capabilities. have partial gap — and which priority addresses it.

03 P1 Business Rules Engine

Closing constraint-enforcement + the first slice of the action layer, on CG’s grain.

Why this first

It is the single highest-leverage move: it lands three article capabilities at once (constraint enforcement, business-logic encapsulation, and an executable action slice), it has an obvious anchor point in code (emit_decision_trace is already the chokepoint for every decision), and it does not require the full ontology to exist before it pays off. Rules can run against a flat projection of the edge + rc today, and tighten as the ontology (P2) arrives.

The library

Proposed foundation: manfred-kaiser/business-rule-engine — a small, dependency-light Python DSL where each rule is a when … then … end block. Conditions are plain Python boolean expressions over a params dict; then lines call registered functions. This maps cleanly onto CG: params = the decision being recorded, registered functions = our enforcement & side-effect verbs.

# business_rule_engine — native shape
from business_rule_engine import RuleParser

def reject(reason):       # a registered action verb
    raise RuleViolation(reason)

rules = """
rule "approval over $10k needs a manager"  priority 10
when
    relation_type == "APPROVES"
    and amount > 10000
    and approver_role != "manager"
then
    reject("Approvals over $10,000 require a manager")
end
"""

parser = RuleParser()
parser.register_function(reject)
parser.parsestr(rules)
parser.execute({"relation_type":"APPROVES", "amount":25000, "approver_role":"analyst"})
# → RuleViolation: Approvals over $10,000 require a manager

How a CG decision becomes rule params

The bridge is a deterministic projection: flatten the edge, its RelationContext, and (later) the typed attributes of the head/tail entities into one dict the engine can evaluate. No magic — one function, one table of derived fields, easy to test.

def project_decision(src, tgt, relation_type, rc, ontology=None) -> dict:
    return {
        "src": src, "tgt": tgt, "relation_type": relation_type,
        "approved_by": rc.approved_by,
        "approved_via": rc.approved_via,
        "policy_ref": rc.policy_ref,
        "confidence": rc.confidence_score,
        "valid_from": rc.valid_from, "valid_until": rc.valid_until,
        "is_active": rc.is_active(),
        # parsed numerics from quantitative_data (e.g. "20% discount", "$25,000")
        "amount": parse_amount(rc.quantitative_data),
        "percent": parse_percent(rc.quantitative_data),
        # P2: typed entity attributes & roles, when the ontology exists
        "approver_role": (ontology and ontology.role_of(rc.approved_by)),
    }

Where rules fire (enforcement points)

rule "large discount must name an approver" priority 20
when
    relation_type == "GRANTS_DISCOUNT"
    and percent > 0.15
    and approved_by is None
then
    flag("Discount >15% recorded with no approver — needs sign-off")
end

rule "expired authority" priority 15
when
    relation_type == "APPROVES"
    and is_active == False
then
    flag("Approval references an authority outside its validity window")
end

04 P1 Fuzzy fact matching — past exact-match brittleness

The objection that breaks a naïve Business Rules Engine on AI data, and the cheap fix: static-vector similarity as a rule predicate.

The flaw

A classic rules engine matches exactly: relation_type == "APPROVES". But in CG almost every field a rule wants to read is free-text, LLM-extracted, and paraphrased — the same decision surfaces as APPROVES, GRANTED_APPROVAL, "signed off on", "authorized". Exact string equality misses all but one spelling, so a hand-written rule silently under-fires. On the data CG actually holds, exact matching is not a minor limitation — it is disqualifying.

Why model2vec is the right middle tier

The rules gate runs synchronously on every decision write (the pre-emit hook, §03). That latency budget is what rules out the alternatives — an LLM judge or an OpenAI-embedding call per field per event is far too slow and (for the LLM) non-deterministic. model2vec is built for exactly this shape:

Static embeddings (distilled token vectors, no live transformer pass) make per-event encoding sub-millisecond, so hundreds of rules × a few anchor concepts each cost nothing per write. Candidate models: potion-retrieval-32M (tuned for matching) or potion-base-8M (smallest); potion-multilingual-128M if non-English flows appear.

Integration: sim() as a registered DSL predicate

No fork of the rules engine. business-rule-engine’s when is a Python boolean expression over registered functions, so we simply register a similarity function backed by model2vec — and it becomes available in every rule. It returns a float (not a bool with a hidden threshold) so the threshold stays visible in the rule text, which matters for both the AI author (§05) and human review.

rule "approval control"
when
    sim(relation_type, APPROVAL) > 0.62     # SOFT: free-text relation, paraphrase-tolerant
    and amount > 10000                     # HARD: structured number — never fuzzy
    and is_active == True                    # HARD: structured flag
then
    reject("Approvals over $10k need a manager")
end

The Concept Catalog — don’t embed ad-hoc strings

Rather than each rule embedding its own anchor phrase, define named concepts per workspace, each backed by a few example phrases and embedded once at compile time (anchors are static; only the incoming fact is embedded per event). Rules reference concepts by name (APPROVAL above). Matching against the max similarity over several examples is far more stable than a single anchor.

APPROVAL := ["approved", "signed off on", "authorized", "granted approval"]
REFUND   := ["refund issued", "money returned", "reimbursed"]
ESCALATE := ["escalated to", "raised to management", "flagged for review"]

Decisions that make or break it

05 P1 AI-generated DSL — a rule author per use case

The adoption unlock: turn natural-language policy into validated, executable rules.

Hand-writing DSL is the bottleneck the article’s “expert-authored” principle quietly assumes. We invert it: a domain expert states policy in plain language; an AI agent drafts the DSL, grounded in what fields and verbs actually exist, then we validate before it can ever fire. The agent is constrained, not trusted — every draft passes a parse check and a dry-run on fixtures before a human approves it.

Generation loop

1. Ground the agent. Hand it the capability manifest: available params fields (from the projection), registered action verbs (reject, flag, notify…), the ontology vocabulary (P2: object types, properties, link types), and a few canonical rule examples.
2. Draft. Agent emits one or more when…then…end blocks from the NL policy, restricted to grounded fields and verbs only.
3. Validate (hard gate). RuleParser.parsestr() must parse; every referenced field must exist in the projection; every then verb must be registered. Parse/lint failure → auto-repair prompt back to the agent (bounded retries).
4. Dry-run. Execute the candidate against fixture decisions (positive + negative cases the agent also proposes). Show the human exactly which fixtures trigger.
5. Explain & approve. Agent renders the rule back into NL (“this blocks…”) for review. Human approves → rule is stored, versioned, and enabled per workspace. Rejection feeds back as guidance.

rule "large discount needs finance review"  priority 10
when
    sim(relation_type, "APPROVAL") > 0.4     # soft — paraphrase-tolerant
    and percent > 0.15                     # hard
    and approved_via == "slack"             # hard
then
    flag("Discount >15% approved over Slack — route to Finance for review")
end

06 P1 Integration — how the Business Rules Engine works with CG

The end-to-end picture: where a decision meets the rules gate, and the concrete plan to wire the (already-built) sim() predicate into CG.

The whole flow at a glance

How a decision finds its edge (and where the two paths converge)

The part worth stating plainly: a CG edge has no separate ID. Its identity is the ordered pair of entity names — (head, tail) = (src, tgt). “Associating a decision with the existing graph” just means resolving that pair and looking it up. Both inputs do the same four things to get there.

1. Resolve the key. Entity names are sanitized / normalized / truncated so “Sarah Chen” always lands on the same key; the decision’s identity becomes (src, tgt).
2. Look up the edge. get_edge(src, tgt) — found → it already carries an rc; not found → a new edge (and any missing entity nodes) is created.
3. Merge the rc. The incoming context is unioned with whatever the edge already holds via RelationContext.merge() (sentences deduped, first-non-null scalars, max confidence). On ingestion, multiple chunks naming the same pair are merged the same way by _collect_relation_context.
4. Finalize. upsert_edge(src, tgt, …) writes the merged edge.

Runtime: the pre-emit gate, step by step

Every decision — whether extracted from a document or posted to /graph/decision/emit — passes one chokepoint before it is written. That chokepoint is where the rules engine lives.

1. A decision arrives as (src, tgt, relation_type, rc) — from CG extraction or the emit endpoint.
2. Project it to a flat params dict via project_decision() (edge + rc +, later, typed ontology attributes from P2).
3. Evaluate the workspace’s rules. Conditions mix soft predicates (sim(relation_type,"APPROVAL") > 0.4, model2vec-backed) and hard ones (amount > 10000, is_active == True).
4. Gate the outcome: no rule trips → PASS (persist as today); a flag() rule trips → FLAG (persist with needs_review); a reject() rule trips → REJECT (HTTP 422, nothing written).
5. Record the why. On FLAG/REJECT, the matched concept, score, and threshold are written to the audit record — fuzzy matches stay as explainable as amount > 10000.

Wiring plan — next steps to connect sim()

The predicate is done; the remaining work is plumbing it into the decision path. Each row is an independent, reviewable PR. built ships today; to build is next.

Endpoints (alongside /graph/decisions*)

Worked example — one decision, end to end

One concrete decision traced through every step of the diagram above. The numbers are real (sim() measured on potion-retrieval-32M). The rule below was authored earlier via §05; here it fires. Outcome is a FLAG — so the decision persists and leaves an audit trail.

rule "large discount needs finance review"  priority 10
when
    sim(relation_type, "APPROVAL") > 0.4     # SOFT — model2vec sim()
    and percent > 0.15                     # HARD — structured number
    and approved_via == "slack"             # HARD — controlled vocabulary
then
    flag("Discount >15% approved over Slack — route to Finance for review")
end

# source chunk (Aug 14)
Sarah Chen: "Approved the 20% discount for MegaCorp — they were about to churn to
Salesforce. Good through Q4."

{
  "src": "Sarah Chen", "tgt": "MegaCorp",
  "relation_type": "GRANTED_APPROVAL",        # ← paraphrase, NOT the literal "APPROVES"
  "rc": {
    "decision_trace": "Approved 20% discount; retention risk (Salesforce)",
    "quantitative_data": "20% discount",
    "approved_by": "Sarah Chen", "approved_via": "slack",
    "valid_until": "2026-12-31", "confidence_score": 0.96
  }
}

{
  "relation_type": "GRANTED_APPROVAL",
  "percent": 0.20,            # parsed from "20% discount"
  "approved_by": "Sarah Chen",
  "approved_via": "slack",
  "is_active": true,           # valid_until 2026-12-31 ≥ today
  "confidence": 0.96
}

# 1. graph edge (upserted, now carrying the review flag)
Sarah Chen ─[GRANTED_APPROVAL]→ MegaCorp   needs_review=true

# 2. decisions_vdb — decision_trace indexed for precedent search (§ find_precedents)

# 3. audit record — the "why", as explainable as a numeric predicate
{
  "rule": "large discount needs finance review",
  "outcome": "FLAG",
  "matched_concept": "APPROVAL",   "score": 1.00,   "threshold": 0.40,
  "reason": "Discount >15% approved over Slack — route to Finance for review",
  "model_id": "minishlab/potion-retrieval-32M"
}

07 P2 Ontology creation

Give the rules — and the graph — a typed vocabulary to stand on.

Today CG extracts against an open list of entity types (constants.py), relation “types” are free-text keywords, properties are untyped, and edges are effectively undirected (the edge-context route has to probe both directions — context_graph_routes.py:517). P2 introduces a real schema so that rules can reference Order.value or Employee.role with confidence, and so extraction can be validated rather than trusted.

What the schema layer defines

Authoring: top-down + AI-assisted (hybrid)

The article’s principle is “expert-defined before extraction.” We keep the expert in charge but let an agent do the heavy lifting — symmetric with the P1 DSL author:

• Seed from existing signals: the current entity-type list, a sample of extracted edges, and (optionally) an imported DB schema.
• Draft an ontology (types, properties, link types, cardinality) with an agent; expert edits and confirms.
• Bind extraction prompts to the confirmed schema so future ingestion is schema-aware.

08 P3 Backlog gaps — documented for future discussion

Captured so they are not lost. Each is a later conversation, not a current commitment.

09 Sequencing & dependencies

Proposed order. Each phase ships something usable on its own.

10 Open questions to resolve before building

The decisions that change the design. Let’s answer these in the discussion log below.

1. Enforcement default: should the pre-emit gate reject (hard 422) or flag (write + needs_review) by default? Per-rule severity?
2. Rule scope: rules per-workspace only, or also global/shared templates inherited by workspaces?
3. Agent trust boundary: may the rule-author agent propose new action verbs (code), or only compose registered ones?
4. Fixtures: expert-authored, sampled from live edges, or agent-synthesised-then-trimmed?
5. Numeric parsing: how robust must parse_amount/parse_percent be over free-text quantitative_data before P2 gives us typed numbers? Risk of mis-enforcement.
6. Ontology standard: RDF/OWL+SHACL vs CG-native schema (lean: native first).
7. Model: reuse CG’s LLM binding for both agents, or a dedicated authoring model?

11 Discussion log

Append decisions and notes here as we talk. Newest at the bottom.