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}")| Module | What it detects | Example |
|---|---|---|
| Patterns | Recurring cycles, trends | "Your activity has a weekly cycle (r=0.85)" |
| Anomalies | Unusual spikes, drops, gaps | "No activity in 72 hours (your average gap is 18h)" |
| Forecasting | Future values with confidence | "Activity forecast: declining over next 14 periods" |
| Topics | Emerging, growing, declining themes | "Emerging topic: 'kubernetes' — appeared recently" |
| Correlations | Connections between signals | "Email volume leads stress by 2 days (r=0.65)" |
| Sequences | Repeated action patterns | "After 'search', you usually 'code' (78% of the time)" |
| Recommendations | What to read/watch/do next | "Recommended book: 'Designing Data-Intensive Applications'" |
| Anticipation | Compound insights from all modules | "Multiple signals converging on 'kubernetes': 4 indicators" |
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]').
git clone https://github.com/Wyrdsekai/oracle-core.git
cd oracle-core
uv sync --extra dev
uv run pytest tests/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)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.
# 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 meimport 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)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);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 JapaneseEvery 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"}| Tier | Model | Size | Needs |
|---|---|---|---|
| Classical | Fourier + trend (built-in) | 0 | nothing — ships with the package |
| Chronos-Bolt-Tiny | 8M params, zero-shot | ~20MB | the forecast extra |
| Chronos-2 | 120M params, zero-shot | ~250MB | the forecast extra |
| TimesFM | 500M params, strongest | ~1GB | Separate install |
Phone (Kotlin/TS): Classical built-in. Chronos-Bolt-Tiny via ONNX Runtime (20MB).
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.
Apache 2.0. See LICENSE.