PromptMatrix Developer Documentation

PromptMatrix is a runtime prompt governance control plane for AI systems and multi-agent swarms. It centralizes your LLM system instructions, agent personas, and tool schemas into a version-controlled, evaluated, and approval-gated registry—served in sub-15ms via edge caching without ever redeploying code.

⚡ 60-Second Quickstart

Retrieve any live prompt at runtime using your API key (pm_live_... or pm_dev_...):

# pip install promptmatrix
from promptmatrix import PromptMatrix

pm = PromptMatrix(api_key="pm_live_your_key_here")

# 1. Fetch live prompt with dynamic variable substitution
prompt = pm.serve("assistant.system", company="Acme Corp", user_role="Admin")
print(prompt.content)

# 2. Pass to OpenAI, Anthropic, or Agent Swarm
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "system", "content": prompt.content}, {"role": "user", "content": "Hello!"}]
)

# 3. Log execution telemetry back to PromptMatrix
pm.feedback(
    prompt_key="assistant.system",
    version_id=prompt.version_id,
    outcome="success",
    latency_ms=450,
    tokens_used=120
)

# Hot-path prompt retrieval (sub-15ms cached)
curl -X GET "https://api.promptmatrix.io/pm/serve/assistant.system?vars=company=Acme,role=Admin" \
     -H "Authorization: Bearer pm_live_your_key_here" \
     -H "Accept: application/json"

// Zero external dependencies (native fetch)
const res = await fetch("https://api.promptmatrix.io/pm/serve/assistant.system?format=json", {
  headers: { Authorization: "Bearer pm_live_your_key_here" }
});
const { content, version_id } = await res.json();
console.log("Active prompt:", content);

🤖 Multi-Agent Swarm Integrations

1. OpenClaw Swarm Persona Registry

In multi-agent architectures (like OpenClaw), hardcoded personas cause system-wide fragility. Govern each agent's identity dynamically:

import openclaw
from promptmatrix import PromptMatrix

pm = PromptMatrix(api_key="pm_live_xxxx")

# Fetch governed personas for swarm agents
lead_prompt = pm.serve("openclaw.lead_analyst.system")
coder_prompt = pm.serve("openclaw.code_synthesizer.system")

lead_agent = openclaw.Agent(
    name="LeadAnalyst",
    instructions=lead_prompt.content,
    tools=[openclaw.tools.WebSearch()]
)

coder_agent = openclaw.Agent(
    name="CodeSynthesizer",
    instructions=coder_prompt.content
)

# Launch swarm — any prompt edit in PromptMatrix updates the next run instantly!
swarm = openclaw.Swarm(agents=[lead_agent, coder_agent])
swarm.run("Analyze market trends for Q3")

2. LangGraph Node Hot-Patching

Hot-patch prompts inside state graph nodes without redeploying microservices:

from langgraph.graph import StateGraph
from promptmatrix import PromptMatrix

pm = PromptMatrix(api_key="pm_live_xxxx")

def reasoning_step(state):
    # Dynamically pull prompt for this node
    prompt = pm.serve("langgraph.node.reasoning")
    
    response = model.invoke(prompt.content + "\nState: " + state["input"])
    
    # Report telemetry for node-level observability
    pm.feedback(prompt_key="langgraph.node.reasoning", version_id=prompt.version_id, outcome="success")
    return {"result": response}

workflow = StateGraph(dict)
workflow.add_node("reasoning", reasoning_step)

3. CrewAI Agent Backstory Governance

from crewai import Agent, Crew, Task
from promptmatrix import PromptMatrix

pm = PromptMatrix(api_key="pm_live_xxxx")

researcher = Agent(
    role="Senior Market Researcher",
    goal="Discover high-growth AI SaaS vectors",
    backstory=pm.serve("crewai.researcher.backstory").content,
    verbose=True
)

📦 Python SDK Reference (`promptmatrix-sdk`)

The official Python SDK is 100% zero-dependency (implemented purely with Python standard library urllib), guaranteeing zero conflicts with your existing ML packages.

• pm.serve(key, **vars) — Sub-15ms cached hot-path fetch.
• pm.feedback(key, version_id, outcome, latency_ms, tokens_used) — Observability trace logger.
• pm.prompts.create(env_id, key, content) — Programmatic prompt creation.
• pm.prompts.create_version(prompt_id, content) — Draft a new version.
• pm.prompts.approve(prompt_id, version_id) — Gate approval flow.
• pm.prompts.rollback(prompt_id, version_id) — Instant 1-click rollback.

📖 Interactive OpenAPI Reference

Explore all 44 live endpoints, request schemas, parameters, and authentication requirements:

🏠 Self-Hosting (OSS Community Tier)

PromptMatrix is fully open source (MIT Licensed). Run the entire stack locally with SQLite or PostgreSQL:

# 1. Clone repository
git clone https://github.com/PromptMatrix/Promptmatrix.git
cd Promptmatrix

# 2. Run with Docker Compose
docker compose up -d

# 3. Or launch with native Python
./start.sh    # Windows: start.bat
# Dashboard opens automatically at http://localhost:8000/dashboard

🛡️ Security & BYOK Architecture

• API Key Security: All API keys are SHA-256 hashed. Full keys are displayed once at creation and never stored in plaintext.
• BYOK (Bring Your Own Key) Zero-Retention: Model keys supplied for LLM evaluations are AES-256-GCM encrypted in memory, used once, and explicitly deleted from Python memory scope.
• High Availability & Fail-Open: If edge cache or Redis undergoes maintenance, the serve router gracefully falls back to database lookup, preventing agent downtime.