Precedent Search
Precedent search finds relevant past decisions that are similar to a current situation. It uses embedding similarity on decision rationale, combined with temporal relevance scoring and outcome confidence weighting, to surface the most useful historical precedents for decision-making.
Overview
When agents or users need to make a decision, precedent search answers: "What similar decisions were made in the past, and what were their outcomes?" This is powered by the DecisionRankingService and the BiTemporalStore.
Source: data-plane/ai-service/src/context_graph/services/decision_ranking_service.py
Ranking Factors
Precedent search uses multi-factor scoring to rank past decisions:
| Factor | Weight | Description |
|---|---|---|
| Semantic Similarity | 0.35 | Cosine similarity between decision rationale embeddings |
| Temporal Relevance | 0.20 | Recency decay -- more recent decisions score higher |
| Outcome Confidence | 0.25 | Historical success rate of similar decisions |
| Context Match | 0.10 | Matching entity types and domains |
| Entity Type Match | 0.05 | Whether the subject entity types are the same |
| Domain Match | 0.05 | Whether the decisions are in the same domain |
API Usage
Search via the Unified Search Service
results = await service.search(SearchQuery(
query="Deploy fraud detection model to production",
tenant_id="acme",
mode=SearchMode.PRECEDENT,
scope=SearchScope.DECISIONS,
top_k=5,
))Search via the Hybrid Store Directly
precedents = await hybrid_store.find_decision_precedents(
decision_urn="urn:matih:decision:acme:deploy-fraud-v3",
tenant_id="acme",
top_k=5,
min_relevance=0.5,
)Search via the BiTemporal Store
precedents = await bitemporal_store.search_precedents(
tenant_id="acme",
decision_type="model_deployment",
characteristics={"model_type": "classification"},
limit=5,
)Outcome Statuses
Precedent search considers the outcome of past decisions when ranking:
| Status | Description | Impact on Score |
|---|---|---|
SUCCESSFUL | Decision led to a positive outcome | Boosts score |
PARTIALLY_SUCCESSFUL | Mixed results | Neutral |
FAILED | Decision led to a negative outcome | Still returned with lower score |
PENDING | Outcome not yet known | Returned with uncertainty flag |
UNKNOWN | Outcome was never recorded | Lowest confidence |
Temporal Decay
More recent decisions are weighted higher using exponential decay:
temporal_score = exp(-age_days / half_life_days)The default half-life is 90 days, meaning a 90-day-old decision scores at 50% of its original temporal relevance. This can be configured per-tenant.
Example Use Cases
| Scenario | Query | Expected Results |
|---|---|---|
| Model deployment | "Deploy churn model v3" | Past churn model deployments with outcomes |
| Schema change | "Alter customer table schema" | Past schema migrations and their impacts |
| Alert configuration | "Set up anomaly alerts for revenue" | Past alerting configurations for similar metrics |
| Access grant | "Grant read access to sales data" | Past data access decisions for similar datasets |