episteme-sdk 0.1.2

Episteme SDK: A unified framework for advanced uncertainty quantification (KAIROS) and intelligent memory management (MAKS) in LLM applications.

Episteme SDK

Episteme SDK is a unified Python library designed to bring advanced uncertainty quantification and intelligent, long-term memory management to Large Language Model (LLM) applications.

By integrating the KAIROS uncertainty engine and the MAKS memory management system, Episteme gives AI agents the ability to deeply evaluate the reliability of their own claims, while simultaneously building an evolving, context-aware memory over time.

---

📦 Installation

Install via pip:

pip install episteme-sdk

(Requires Python 3.9+)

---

🚀 Quickstart

Get started in just a few lines of code. Episteme manages both the LLM uncertainty evaluation and the memory state under the hood.

from episteme import Episteme, EpistemConfig

# 1. Initialize the configuration with your API keys
# (Episteme relies on Nvidia NIM for LLM inference and embeddings)
config = EpistemConfig(
    nim_api_key="YOUR_NVIDIA_NIM_API_KEY",
    nim_model="meta/llama-3.1-70b-instruct"
)

# 2. Instantiate the SDK
episteme_client = Episteme(config)

# 3. Query the system
result = episteme_client.query("What causes diabetes, and is it reversible?")

# 4. View the processed answer and the uncertainty breakdown
print(f"Answer:\n{result['answer']}\n")

print("Uncertainty Analysis:")
for claim in result["claims"]:
    print(f"[{claim['zone']}] {claim['text']}")
    print(f"   -> Entropy: {claim['H_e_norm']:.4f}, Gradient: {claim['G_norm']:.4f}, Consistency: {claim['Cons']:.4f}")
    print(f"   -> Final Uncertainty (U): {claim['U']:.4f}\n")

---

🧠 Core Architecture & Features

Episteme SDK is built on two foundational pillars:

1. KAIROS: Per-Claim Uncertainty Quantification

Standard LLMs output text confidently, even when hallucinating. KAIROS breaks down the model's generated answer into atomic "claims" and rigorously evaluates each one to determine how much it can be trusted.

It calculates a unified Uncertainty Score ($U$) based on three mathematical dimensions:

• Epistemic Entropy ($H_e$): Evaluates the model's internal confidence and probability distributions for the tokens making up the claim.
• Structural Gradient ($G$): Assesses the semantic importance and impact of the claim within the overall context of the answer.
• Consistency ($Cons$): Measures how often the model agrees with this specific claim across multiple, independent resampling passes (self-consistency).

Based on the final $U$ score, KAIROS assigns each claim to a Reliability Zone:

• 🟢 SOLID ($U < 0.03$): The claim is highly reliable and grounded. You can trust it.
• 🟡 GRADIENT ($0.03 \le U < 0.08$): The claim is moderately reliable. Verification is recommended before taking critical actions.
• 🔴 FAULT LINE ($U \ge 0.08$): The claim is highly uncertain or inconsistent. Treat this as a potential hallucination and verify strictly.

2. MAKS: Intelligent Memory Management

LLM agents often suffer from limited context windows or bloated vector stores full of irrelevant data. MAKS solves this by mimicking human memory consolidation.

MAKS ensures that critical, frequently accessed information persists across queries, while stale or less important information naturally decays and archives itself.

• Active Memory & Ghost Store: Highly relevant memories stay in the "Active Window" (injected into the LLM context). When memories degrade below a survival threshold, they are moved to the "Ghost Store" (a scalable vector database).
• Dynamic Reconsolidation: If a user's new query semantically matches an archived memory in the Ghost Store, MAKS automatically "reconsolidates" it, pulling it back into Active Memory.
• Survival Engine ($S$): Every memory unit has a survival score calculated dynamically based on:
  • Base importance ($\theta$)
  • Time since last access ($\Delta t$)
  • Frequency of access (Reinforcement)
  • Semantic connections to other active memories.

---

⚙️ Configuration Options

You can deeply customize the behavior of both KAIROS and MAKS via the EpistemConfig object.

from episteme import EpistemConfig

config = EpistemConfig(
    nim_api_key="YOUR_KEY",
    nim_url="https://integrate.api.nvidia.com/v1",
    nim_model="meta/llama-3.1-70b-instruct",
    
    # MAKS Memory Parameters
    maks_alpha=1.0,         # Reinforcement multiplier for memory access
    maks_beta=0.5,          # Decay baseline parameter
    maks_lambda_decay=0.1,  # Rate of time-based decay
    maks_theta_full=0.9,    # Base importance threshold for SOLID memories
    maks_max_tokens=4000,   # Maximum allowed tokens in the Active Window
    
    # KAIROS Thresholds
    phi_s=0.03,             # Threshold for SOLID zone (U < 0.03)
    phi_f=0.08              # Threshold for FAULT LINE zone (U >= 0.08)
)

---

📖 Advanced Usage: Inspecting Memory State

The Episteme client also allows you to inspect the ongoing MAKS memory state at any time:

# Get a summary of the current memory status
memory_summary = episteme_client.get_memory_summary()

print(f"Active Memories: {memory_summary['active_units']}")
print(f"Archived (Ghost) Memories: {memory_summary['ghost_units']}")
print(f"Total Tokens in Active Window: {memory_summary['estimated_tokens']}")

You can use this to build fully autonomous agents that maintain long-term context across sessions without blowing up your LLM context limits or costs.

---

📄 License

This project is licensed under the MIT License.