Mikoshi Curiosity

Explore any state space. Find what you didn't know you were looking for.

Recommendation engines predict what you'll like. Curiosity engines find what you don't know you'd like.

Mikoshi Curiosity is a domain-agnostic exploration engine that uses intrinsic motivation, state memory, and diversity pressure to discover interesting things in any state space — datasets, text corpora, graphs, parameter spaces, or APIs.

Inspired by Go-Explore and intrinsic motivation research.

Quick Start

pip install mikoshi-curiosity
# With extras:
pip install mikoshi-curiosity[data]  # pandas support
pip install mikoshi-curiosity[all]   # pandas + matplotlib

Examples

🔍 Find Anomalies in a Dataset

import pandas as pd
from mikoshi_curiosity import CuriosityEngine
from mikoshi_curiosity.contexts.dataset import DatasetSpace

df = pd.read_csv("sales_data.csv")
space = DatasetSpace(df)
engine = CuriosityEngine(space, strategy="novelty")

seed = space.get_state("0")
result = engine.explore(seed, budget=200)

print(result.summary())
for d in result.top(5):
    print(f"  [{d.score:.2f}] Row {d.state.id}: {d.reason}")
    print(f"         {d.state.features}")

📚 Explore a Text Corpus

from mikoshi_curiosity import CuriosityEngine
from mikoshi_curiosity.contexts.text import TextSpace

docs = [
    {"id": "paper1", "text": "Deep learning for image recognition..."},
    {"id": "paper2", "text": "Quantum entanglement in biological systems..."},
    # ... hundreds of papers
]

space = TextSpace(docs)
engine = CuriosityEngine(space, strategy="diversity")
result = engine.explore(space.get_state("paper1"), budget=100)

# Find bridging documents that connect different topics
for d in result.top(10):
    print(f"  {d.state.id}: {d.reason}")

🎛️ Explore a Parameter Space

from mikoshi_curiosity import CuriosityEngine
from mikoshi_curiosity.contexts.numeric import NumericSpace

def simulate(params):
    """Your simulation / evaluation function."""
    return complex_score(params["gravity"], params["friction"], params["elasticity"])

space = NumericSpace(
    dimensions={"gravity": (0, 20), "friction": (0, 1), "elasticity": (0.1, 5)},
    eval_fn=simulate,
)
engine = CuriosityEngine(space, strategy="balanced")
result = engine.explore(space.get_random(5), budget=500)

# Find interesting parameter combinations, phase transitions, sweet spots
for d in result.top(10):
    print(f"  Score: {d.score:.3f} | Params: {d.state.features}")

🕸️ Explore a Network

from mikoshi_curiosity import CuriosityEngine
from mikoshi_curiosity.contexts.graph import GraphSpace

space = GraphSpace(
    nodes=["alice", "bob", "carol", ...],
    edges=[("alice", "bob"), ("bob", "carol"), ...],
)
engine = CuriosityEngine(space, strategy="novelty")
result = engine.explore(space.get_state("alice"), budget=100)

# Discover bridge nodes, structural holes, unexpected clusters

Strategies

API Reference

Core

• State — A point in exploration space (id, features, embedding, metadata)
• StateSpace — Abstract space to explore (subclass for your domain)
• CuriosityEngine — The exploration engine
• ExplorationMemory — Go-Explore style state archive
• PredictionModel — Online model for surprise detection
• Discovery — A single interesting finding with score and reason
• ExplorationResult — Container with discoveries, stats, and memory

Built-in Contexts

Custom State Space

from mikoshi_curiosity import StateSpace, State

class MySpace(StateSpace):
    def get_neighbors(self, state, n=10):
        ...  # Return nearby states

    def get_random(self, n=10):
        ...  # Return random states

    def get_state(self, id):
        ...  # Lookup by id

    def embed(self, state):
        ...  # Return numpy vector

    def size(self):
        ...  # Approximate space size

Visualization

from mikoshi_curiosity.viz import plot_exploration, plot_discovery_scores

fig = plot_exploration(result)   # 2D PCA projection with discoveries highlighted
fig = plot_discovery_scores(result)  # Score breakdown bar chart

Requires pip install mikoshi-curiosity[viz].

Design Philosophy

• Zero external API dependencies — core uses only NumPy
• Domain-agnostic — works with any state space you define
• Go-Explore inspired — maintains an archive of interesting states and explores from frontiers
• Multiple signals — novelty, surprise, diversity, serendipity, diminishing returns
• Online learning — prediction model updates as you explore
• Resumable — ExplorationResult contains full memory state

Built by Mikoshi Ltd