oracle-core

Personal prediction engine. Detects patterns, anomalies, trends, and correlations in your data. Recommends what to read, watch, or do next based on where you're going, not where you've been.

Local. Private. Yours.

from oracle_core import Oracle, Event
from datetime import datetime

oracle = Oracle()

# Feed it events from any source
oracle.ingest("me", [
    Event(timestamp=datetime.now(), source="search", event_type="search",
          content="distributed systems consensus algorithms"),
    Event(timestamp=datetime.now(), source="journal", event_type="entry",
          content="feeling productive, deep focus today"),
])

# Train (runs all analysis modules)
oracle.train("me")

# Get predictions
for p in oracle.anticipate("me"):
    print(f"[{p.confidence:.0%}] {p.text}")

What It Does

Install

Python (reference implementation)

pip install oracle-core

# With Chronos foundation model forecasting (optional, ~250MB)
pip install 'oracle-core[forecast]'

# With semantic embeddings for better recommendations (optional, ~22MB)
pip install 'oracle-core[embeddings]'

# Everything
pip install 'oracle-core[full]'

Or from a source checkout — git clone the repository, then pip install . with the same extras (pip install '.[full]').

Development

git clone https://github.com/Wyrdsekai/oracle-core.git
cd oracle-core
uv sync --extra dev
uv run pytest tests/

Usage

As a library

from oracle_core import Oracle, Event, RecommendableItem
from datetime import datetime, timedelta

oracle = Oracle(data_dir="~/.my-oracle")

# Ingest events from any source
events = [
    Event(timestamp=datetime.now() - timedelta(hours=i),
          source="app", event_type="search",
          content=f"topic {i % 3}")
    for i in range(100)
]
oracle.ingest("user1", events)

# Run full analysis
result = oracle.train("user1")
print(result)  # {"status": "ok", "events": 100, "models_updated": [...]}

# Get predictions
predictions = oracle.anticipate("user1", min_confidence=0.6)
for p in predictions:
    print(f"[{p.category.value}] {p.text} ({p.confidence:.0%})")

# Get recommendations
books = [
    RecommendableItem(id="b1", title="DDIA", description="distributed systems guide",
                      item_type="book", source="library"),
]
recs = oracle.recommend("user1", books)

# Record feedback (Oracle calibrates itself)
from oracle_core import Feedback, FeedbackOutcome
oracle.feedback("user1", Feedback(
    prediction_id=predictions[0].id,
    outcome=FeedbackOutcome.CORRECT,
    user_engaged=True,
), category=predictions[0].category.value)

As an HTTP server

oracle-server --port 7073

# Or with Docker
docker run -p 7073:7073 wyrdsekai/oracle-core

# Ingest events
curl -X POST http://localhost:7073/v1/ingest \
  -H "Content-Type: application/json" \
  -d '{"user_id":"me","events":[{"timestamp":"2026-03-28T10:00:00","source":"search","event_type":"search","content":"kubernetes"}]}'

# Train
curl -X POST http://localhost:7073/v1/train \
  -H "Content-Type: application/json" \
  -d '{"user_id":"me"}'

# Get predictions
curl -X POST http://localhost:7073/v1/analyze/anticipate \
  -H "Content-Type: application/json" \
  -d '{"user_id":"me","min_confidence":0.5}'

Every data route is under /v1; /health is the one exception, unversioned so a supervisor can check liveness without caring which API generation is running. The JSON Content-Type is required, not decorative — Flask refuses the body without it. The other analyses swap the last path segment: patterns, anomalies, forecast, topics, correlations, sequences.

CLI

# Ingest from JSONL file
oracle-cli ingest me events.jsonl

# Run analysis
oracle-cli train me

# Get predictions
oracle-cli anticipate me

# Interactive mode
oracle-cli shell me

Mobile

Kotlin (KMP — Android/iOS/Desktop)

import oraclecore.Oracle
import oraclecore.Event

val oracle = Oracle()
oracle.ingest("me", listOf(
    Event(timestamp = System.currentTimeMillis(), source = "search",
          eventType = "search", content = "kubernetes deployment")
))
oracle.train("me")
val predictions = oracle.anticipate("me", minConfidence = 0.6)

TypeScript (React Native)

import { Oracle } from 'oracle-core-ts';

const oracle = new Oracle();
oracle.ingest('me', [{
  timestamp: Date.now(), source: 'search',
  eventType: 'search', content: 'kubernetes deployment',
}]);
oracle.train('me');
const predictions = oracle.anticipate('me', 0.6);

i18n

All user-facing text uses i18n keys. Ships with English, Japanese, and Spanish.

from oracle_core.i18n import load_locale
load_locale("ja")  # Switch to Japanese

Every Prediction includes text_key and text_params for downstream re-translation:

p.text        # "Activity has a weekly cycle (r=0.85)"  (resolved)
p.text_key    # "oracle.pattern.periodic"                (key)
p.text_params # {"label": "Activity", "period": "weekly", "r": "0.85"}

Forecasting Tiers

Phone (Kotlin/TS): Classical built-in. Chronos-Bolt-Tiny via ONNX Runtime (20MB).

Architecture

Events (any source) → Ingest → Feature Pipeline → Analysis Modules → Anticipation → Predictions
                                                                          ↑
                                                                    Feedback Loop
                                                                   (calibration)

All data stays local. Per-user isolation. Models are KB-scale (scikit-learn) to MB-scale (Chronos). No cloud. No telemetry.

License

Apache 2.0. See LICENSE.