Skip to content

Oracle Recommendation Engine

The Oracle recommendation engine is a transport-neutral, advisory-only subsystem for AncientOS operator recommendations.

Oracle remains the synthesis layer. The engine does not query Rubick, Beastmaster, provider health, ingest, retention, retrieval, governance, or future evidence sources. Callers supply evidence that has already crossed the appropriate subsystem boundary.

Boundaries

The engine may generate recommendations only. It does not plan, execute, mutate, approve itself, invoke tools, or bypass Lich, Zeus, or Rubick.

Allowed operator actions are:

  • investigate
  • verify
  • approve
  • defer
  • escalate
  • review
  • re-index
  • refresh
  • clean up
  • archive
  • enable
  • disable

Every report declares advisory_only: true, execution_performed: false, and mutation_performed: false.

Evidence Model

The core evidence input is RecommendationEvidenceSource:

  • source_id: stable source identifier
  • source_type: evidence family, such as oracle_self_awareness, provider_health, retrieval, or governance
  • state: one of observed, inferred, unavailable, or unapproved
  • summary: human-readable supplied evidence summary
  • references: source-local evidence references
  • payload: deterministic structured evidence consumed by rules

Missing expected evidence is converted into explicit unavailable recommendations. Missing evidence is never treated as healthy.

recommendation_evidence_from_self_awareness(...) converts an Oracle self-awareness packet into a recommendation evidence source while preserving unavailable self-awareness status.

Recommendation Model

Each Recommendation includes:

  • recommendation_id
  • category
  • title
  • rationale
  • evidence_sources
  • confidence
  • severity
  • operator_action
  • blocked_by
  • governance_requirements
  • rule
  • visible priority metadata

Categories include infrastructure, memory, retrieval, ingestion, capability, governance, provider, storage, and observability.

Rule Registry

Rules are registered as RecommendationRule objects. A rule has:

  • stable rule_id
  • name
  • version
  • category
  • documentation
  • enabled
  • deterministic evaluator function

Rules can be enabled or disabled independently through RecommendationRuleRegistry.with_disabled(...). Future rules can be added to default_recommendation_rule_registry() without changing Oracle core synthesis logic.

Provenance

Every recommendation preserves:

  • source evidence IDs, types, states, summaries, references, and payload
  • the rule ID, name, version, documentation, and matched fields
  • visible priority factors

An operator can answer why a recommendation was generated, which evidence produced it, and which rule produced it without opaque scoring or model reasoning.

Prioritization

Prioritization is deterministic and contains no LLM calls. Ranking considers:

  • severity
  • confidence
  • governance impact
  • operational impact

The score is exposed as priority_score, with component weights exposed in priority_factors.

Extension Points

New evidence sources should provide RecommendationEvidenceSource records rather than being queried by Oracle.

New rules should be deterministic, advisory-only, individually documented, and added through the registry. Rules should cite matched fields and preserve all source provenance needed for replay.