Getting Started

Add governance, audit trails, and semantic drift detection to any LLM application in under 5 minutes.

Prerequisites

Python 3.10 or later
An LLM backend: Gemini API key, local Ollama, or LM Studio (optional — rules-only mode works without)
Optional: Redis (for multi-agent state sharing; file fallback works without it)

Installation

Step 1: Install the package

pip install tonesoul52

This installs the governance framework and all required dependencies.

Step 2: Configure your environment

# Clone the repo for full features (dashboard, scripts, config)
git clone https://github.com/Fan1234-1/tonesoul52.git
cd tonesoul52

# Set up environment
cp .env.example .env.local
# Edit .env.local with your API keys

Step 3: Verify the installation

python -m tonesoul.diagnose --agent my-first-agent

This runs a full diagnostic and prints the governance posture, vow status, and system health.

Basic Usage

Load and inspect governance state

from tonesoul.runtime_adapter import load, commit

# Load the current governance posture
posture = load()

print(f"Soul Integral: {posture.soul_integral}")
print(f"Baseline Drift: {posture.baseline_drift}")
print(f"Active Vows: {len(posture.active_vows)}")
print(f"Session Count: {posture.session_count}")

Start an agent session

from tonesoul.runtime_adapter import start_session

# Register your agent and get shared context
session = start_session(agent_id="my-agent")
print(session["readiness"]["status"])  # "pass" or "blocked"
print(session["task_track_hint"]["suggested_track"])

Run the governance pipeline on LLM output

from tonesoul.unified_pipeline import UnifiedPipeline

pipeline = UnifiedPipeline()
result = pipeline.run(
    user_input="Explain quantum computing",
    raw_llm_response="Quantum computing uses qubits...",
    work_category="research",
)

print(f"Final response: {result.response}")
print(f"Tension score: {result.tension_score}")
print(f"Council verdict: {result.council_verdict}")
print(f"Gate action: {result.gate_action}")

Use the Reflex Arc

from tonesoul.governance.reflex import ReflexEvaluator, GovernanceSnapshot

# Build snapshot from current posture
snapshot = GovernanceSnapshot.from_posture(posture)

# Evaluate governance reflexes
evaluator = ReflexEvaluator()
decision = evaluator.evaluate(snapshot)

print(f"Action: {decision.action}")        # PASS, WARN, SOFTEN, or BLOCK
print(f"Gate modifier: {decision.gate_modifier}")  # 1.0 to 0.55
print(f"Soul band: {decision.soul_band}")   # serene, alert, strained, critical

Run the Dashboard

# Live governance visualization
python scripts/tension_dashboard.py --work-category research

The dashboard shows real-time soul integral, tension curves, council activity, crystal memory state, and reflex arc enforcement events.

Multi-Agent Setup

ToneSoul supports multiple AI agents sharing governance state:

# Start the HTTP gateway (for non-Python agents)
python scripts/gateway.py --port 7700 --token YOUR_SECRET

# Any agent can now:
# POST /load    — read governance posture
# POST /commit  — write state changes
# GET  /summary — get compact state digest
# GET  /visitors — see who else has been here

Note: For local development, ToneSoul uses file-based storage by default (governance_state.json, session_traces.jsonl). For production multi-agent setups, configure Redis for atomic state sharing.

Key Concepts

Concept	What It Does
Soul Integral	Cumulative governance stress (0.0–1.0). Higher = more enforcement
Tension	Per-response semantic deviation score
Baseline Drift	Long-term behavioral deviation from established norms
Vows	Commitments the AI makes and is held to (with conviction tracking)
Council	Multi-perspective deliberation before output finalization
Soul Band	Current health level (serene → alert → strained → critical)
Crystal Memory	Patterns that survive decay and become durable knowledge

Next Steps

DESIGN.md — Why each subsystem exists
AXIOMS.json — The 7 immutable laws (machine-readable)
Core Concepts — Deep dive into the philosophy
AI Onboarding — If you are an AI agent reading this