kiori 1.0.0

A minimalist library with as few dependencies as possible.

Kiori 🧠

Kiori is a minimalist, highly extensible Python framework for building LLM-based agents. True to its philosophy, it eschews bloated dependencies in favor of a clean, composable architecture.

Kiori introduces advanced contextual memory and execution capabilities directly to your LLM pipelines, featuring a Weighted Pattern Matcher, Markov Chain Routing, and a Replay Buffer for robust multi-turn conversations.

---

Architecture Overview

Kiori's strength lies in how it seamlessly merges different context paradigms before sending prompts to an LLM:

1. Long-Term Memory (LTM) & Weighted Pattern Matcher: Powered by Milvus Lite, the LTM stores past interactions and few-shot examples as vector embeddings. When a new prompt arrives, Kiori performs semantic search (Cosine Similarity). High-confidence matches are dynamically duplicated (scaled) to heavily influence the LLM's behavior via the Weighted Pattern Matcher mechanism.
2. Short-Term Memory (Replay Buffer): Retains the immediate preceding turns of a conversation, ensuring the LLM is acutely aware of recent context.
3. Markov Chain Router: Resolves ambiguity by applying a predefined transition matrix $P(Action_B | Action_A)$. The semantic score from the LTM is combined with the Markov probability to calculate a final score: Score = alpha * cosine_score + beta * P(B|A). This ensures logical flow between actions even if user input is vague.
4. Execution Pipeline: Automatically parses the LLM's string output, extracts action signatures and arguments, and executes the mapped Python code.

---

Installation

# Core minimal installation
pip install kiori

# Install with memory module dependencies (pymilvus & sentence-transformers)
pip install "kiori[memory]"

Quick Start: End-to-End Workflow

Below is a complete example demonstrating how to initialize an Agent, set up its Memory and Router, add Actions, and execute a user prompt.

from kiori.agent import KioriAgent
from kiori.models import Action, ActionExample
from kiori.memory import MilvusLTM, ReplayBuffer
from kiori.router import MarkovRouter

# 1. Setup Memory Modules
ltm = MilvusLTM()  # Automatically initializes a local Milvus Lite vector DB
replay_buffer = ReplayBuffer()

# 2. Add some prior knowledge (Few-shot examples) to LTM
example = ActionExample(
    user_prompt="Check the server status",
    expected_action_text="[ACTION: get_status, ARGS: {}]"
)
ltm.add_examples([example])

# 3. Setup Markov Router (Define state transition probabilities)
transition_matrix = {
    "get_status": {"restart_server": 0.8, "do_nothing": 0.2}
}
router = MarkovRouter(
    transition_matrix=transition_matrix,
    all_actions=["get_status", "restart_server", "do_nothing"]
)

# 4. Initialize the Kiori Agent
agent = KioriAgent(
    ltm=ltm, 
    replay_buffer=replay_buffer, 
    router=router, 
    alpha=0.6, # Weight for Vector Similarity
    beta=0.4   # Weight for Markov Probability
)

# 5. Define and Register Actions (Python Callables)
def get_status() -> str:
    return "Server is running smoothly."

def restart_server() -> str:
    return "Restarting server..."

agent.add_action(Action("get_status", "Fetches current server status", get_status))
agent.add_action(Action("restart_server", "Restarts the server", restart_server))

# 6. Provide an LLM Callback
# This function connects Kiori to your LLM of choice (OpenAI, Anthropic, Gemini, etc.)
def my_llm_callback(prompt: str) -> str:
    # Example: Send the prompt to an LLM API.
    # The prompt natively instructs the LLM to output [ACTION: name, ARGS: {...}]
    
    # Simulating LLM response based on the prompt for demonstration:
    return '[ACTION: get_status, ARGS: {}]'

# 7. Execute the Pipeline
# The Agent retrieves LTM, samples STM, applies Markov weights, shuffles context, 
# prompts the LLM, parses the response, executes the action, and updates the buffer!
result = agent.run("Is the server okay?", llm_callback=my_llm_callback)

print(result) # Output: "Server is running smoothly."

Philosophy

Kiori is built to be lightweight, easy to understand, and independent of bloated external packages. By keeping the core architecture minimalistic, developers have full freedom to compose and customize the AI execution flow without being tied down by rigidly opinionated design patterns.