kore-bridge 0.3.0

LLM integration layer for kore-mind. Runtime-agnostic cognitive bridge.

kore-bridge

LLM integration layer for kore-mind. Runtime-agnostic cognitive bridge.

Middleware cognitivo entre tu app y el LLM. Cache, routing, rate limiting, A/B testing — todo antes de gastar tokens.

Install

pip install kore-bridge                # core (zero deps beyond kore-mind)
pip install kore-bridge[openai]        # + OpenAI
pip install kore-bridge[anthropic]     # + Anthropic
pip install kore-bridge[sc]            # + Selector Complexity routing
pip install kore-bridge[all]           # everything

Quick start (Ollama — 100% local, zero API keys)

ollama pull llama3.2

from kore_mind import Mind
from kore_bridge import Bridge, OllamaProvider

mind = Mind("agent.db")
llm = OllamaProvider(model="llama3.2")  # local, free, private
bridge = Bridge(mind=mind, llm=llm)

# Think with context (auto-remembers)
response = bridge.think("Help me with my proof", user="carlos")

# Observe something
bridge.observe("User prefers concise answers")

# Reflect: LLM generates emergent identity from memories
identity = bridge.reflect()
print(identity.summary)

v0.2 Features

Smart Cache

If the LLM already answered something similar, don't spend tokens.

bridge = Bridge(mind=mind, llm=llm, cache_ttl=3600.0)

r1 = bridge.think("What is P vs NP?")   # calls LLM
r2 = bridge.think("What is P vs NP?")   # cache hit, no LLM call

# Bypass cache when needed
r3 = bridge.think("What is P vs NP?", use_cache=False)  # forces LLM

Cache is per-user: different users get different cached responses.

Rate Limiting

If the user asked the same thing 3 times, respond from memory.

bridge = Bridge(
    mind=mind, llm=llm,
    rate_limit=3,       # max 3 identical queries per window
    rate_window=3600.0, # 1 hour window
)

# 4th identical query → served from cache/memory, no LLM call

Per-user Filtering

Each user gets their own context. The user parameter in think() filters memories by source.

bridge.think("Help with Python", user="alice")  # alice's memories
bridge.think("Help with Rust", user="bob")       # bob's memories

LLM Routing

Simple queries to local Ollama (free), complex ones to GPT-4 (powerful).

from kore_bridge import RouterProvider, OllamaProvider
from kore_bridge.providers import OpenAIProvider

router = RouterProvider(
    providers={
        "fast": OllamaProvider(model="llama3.2"),
        "quality": OpenAIProvider(model="gpt-4o"),
    },
    # Optional: custom routing logic
    route_fn=lambda msgs: "fast" if len(msgs[-1]["content"]) < 100 else "quality",
)

bridge = Bridge(mind=mind, llm=router)
bridge.think("Hi")                    # → Ollama (fast)
bridge.think("Explain quantum...")    # → GPT-4 (quality)
print(router.last_route)             # "quality"

Summarize (used by reflect()) always routes to "quality".

SC Routing (Selector Complexity)

Routing based on formal proof complexity theory. Not heuristics — mathematics.

pip install kore-bridge[sc]

from kore_bridge import SCRouterProvider, OllamaProvider
from kore_bridge.providers import OpenAIProvider
from sc_router import ToolCatalog, Tool

catalog = ToolCatalog()
catalog.register(Tool(
    name="calculator",
    description="Arithmetic calculations",
    input_types={"expression"},
    output_types={"number"},
    capability_tags={"math", "calculate"},
))

router = SCRouterProvider(
    providers={
        "fast": OllamaProvider(model="llama3.2"),
        "quality": OpenAIProvider(model="gpt-4o"),
    },
    catalog=catalog,
)

bridge = Bridge(mind=mind, llm=router)
bridge.think("What is 2+2?")              # SC(0) → Ollama
bridge.think("Analyze and cross-reference market data")  # SC(2+) → GPT-4

print(router.last_sc_level)       # 0, 1, 2, or 3
print(router.last_classification) # full classification evidence

A/B Testing

Compare two providers with the same query and context.

from kore_bridge import Experiment

exp = Experiment(
    mind,
    variant_a=OllamaProvider(model="llama3.2"),
    variant_b=OllamaProvider(model="mistral"),
)

result = exp.run("Explain recursion")
print(result.variant_a)      # llama3.2's response
print(result.variant_b)      # mistral's response
print(result.faster)         # "a" or "b"
print(f"A: {result.time_a_ms:.0f}ms, B: {result.time_b_ms:.0f}ms")

# Batch comparison
results = exp.run_batch(["Q1", "Q2", "Q3"])

By default, remember=False — experiments don't contaminate memory.

Observability

Full tracing when enable_traces=True on the Mind.

mind = Mind("agent.db", enable_traces=True)
bridge = Bridge(mind=mind, llm=llm)

bridge.think("Hello", user="carlos")

traces = mind.traces(operation="bridge.think")
for t in traces:
    print(f"{t.operation} | {t.duration_ms:.0f}ms | cache_hit={t.metadata['cache_hit']}")

Providers

# Ollama (local, recommended for OSS)
from kore_bridge import OllamaProvider
llm = OllamaProvider(model="llama3.2")

# OpenAI
from kore_bridge.providers import OpenAIProvider
llm = OpenAIProvider(model="gpt-4o-mini")

# Anthropic
from kore_bridge.providers import AnthropicProvider
llm = AnthropicProvider(model="claude-sonnet-4-5-20250929")

# Any callable
from kore_bridge import CallableLLM
llm = CallableLLM(lambda msgs: my_custom_api(msgs))

# Router (multiple providers)
from kore_bridge import RouterProvider
llm = RouterProvider(providers={"fast": ollama, "quality": openai})

Backward compatibility

All new parameters have defaults that preserve v0.1 behavior:

# This works exactly the same as v0.1
bridge = Bridge(mind=mind, llm=llm)
bridge.think("Hello")

Demo

python examples/demo_llm.py              # uses llama3.2
python examples/demo_llm.py mistral      # uses mistral

License

MIT