SapixDBSapixDB/Docs
Early Access
Phase 3 · Epigenetics

Epigenetic Profiles

Like epigenetics in biology — the genome (strand) stays intact, only the expression changes. Epigenetic Profiles are named behavioral configurations that change how an agent handles reads, writes, and semantic queries. Switch modes in a single API call; every switch is cryptographically audited on the strand.

✓ Zero strand mutationsActivating a profile never touches the data strand. The underlying nucleotide chain is immutable regardless of which profile is active. Only the agent's runtime behavior changes — enforced at the HTTP layer before any write reaches storage.

The Five Profiles

Every SapixDB agent has exactly five built-in profiles. They cannot be deleted or renamed; you switch between them via a single API call. The default profile is always the starting state on boot.

default
Default
Standard read/write behavior with full LLM semantic planning. The baseline state every agent starts in.
Trigger: startup / manual
✓ Writes✓ Reads✓ LLM✗ Audit
high_load
High Load
LLM inference disabled — semantic queries fall back to the heuristic planner only. Reduces per-query latency during traffic bursts. Writes still succeed.
Trigger: manual / metric monitor
✓ Writes✓ Reads✗ LLM✗ Audit
compliance
Compliance
Every successful strand read emits a signed A2A audit event. Reads and writes both allowed. Use during regulated access windows.
Trigger: manual
✓ Writes✓ Reads✓ LLM✓ Audit
analytics
Analytics
Read-only. Full semantic query (LLM) enabled. Any write attempt returns 403 Forbidden with an explanation of the active profile.
Trigger: manual
✗ Writes✓ Reads✓ LLM✗ Audit
maintenance
Maintenance
Writes suspended (503 Service Unavailable). LLM inference disabled. Reads allowed from sealed segments. Use during maintenance windows.
Trigger: manual
✗ Writes✓ Reads✗ LLM✗ Audit

Automatic High Load detection

A background task runs every 60 seconds comparing writes_total snapshots. When write rate crosses the threshold, high_load activates automatically. When load drops, it reverts — but only if the activation was metric-triggered. Manual activations are never auto-reverted.

delta ≥ 100 writes/min AND active = default
→ activate high_load (metric_triggered: true)
delta < 100 writes/min AND metric_triggered high_load
→ revert to default automatically
ℹ Manual activations are never auto-revertedThe metric monitor only reverts activations it made itself (metric_triggered: true). If you manually switch to high_load (or any other profile), the monitor will not override it — you must revert manually.

HTTP API

List all profiles

GET /v1/epigenetics/profiles
{
  "profiles": [
    {
      "name": "default",
      "display_name": "Default",
      "description": "Standard read/write behavior. No restrictions.",
      "color": "#a6e3a1",
      "allow_writes": true,
      "allow_reads": true,
      "skip_llm": false,
      "force_audit_on_read": false
    },
    { "name": "high_load",   "allow_writes": true,  "skip_llm": true,  ... },
    { "name": "compliance",  "force_audit_on_read": true, ... },
    { "name": "analytics",   "allow_writes": false, "skip_llm": false, ... },
    { "name": "maintenance", "allow_writes": false, "skip_llm": true,  ... }
  ]
}

Get active profile

GET /v1/epigenetics/profile
{
  "active": "compliance",
  "activated_at_ms": 1747003200000,
  "activated_by": "[email protected]",
  "reason": "SOC 2 audit window",
  "metric_triggered": false,
  "config": {
    "name": "compliance",
    "display_name": "Compliance",
    "allow_writes": true,
    "allow_reads": true,
    "skip_llm": false,
    "force_audit_on_read": true,
    "color": "#89b4fa"
  }
}

Activate a profile

PUT /v1/epigenetics/profile
{
  "profile":      "compliance",
  "activated_by": "[email protected]",
  "reason":       "SOC 2 audit window"
}
// → same shape as GET /v1/epigenetics/profile
// → 400 Bad Request for unknown profile names
⚠ Valid profile namesdefault · high_load · compliance · analytics · maintenance
Any other value returns 400 Bad Request.

Activation history

GET /v1/epigenetics/history
{
  "history": [
    {
      "profile":        "default",
      "activated_at_ms": 1747000000000,
      "activated_by":   "system",
      "reason":         null
    },
    {
      "profile":        "high_load",
      "activated_at_ms": 1747001800000,
      "activated_by":   "metric-monitor",
      "reason":         null
    },
    {
      "profile":        "compliance",
      "activated_at_ms": 1747003200000,
      "activated_by":   "[email protected]",
      "reason":         "SOC 2 audit window"
    }
  ]
}

Audit strand

Every profile activation is appended to the agent's strand as a BlockFlags::EPIGENETICS nucleotide (bit 4 · 0x10). This makes the governance history cryptographically immutable — you can verify exactly when each profile was active by replaying the chain. The history endpoint returns the in-memory view; the strand is the authoritative tamper-evident record.

STRAND RECORD (BlockFlags = 0x10 · EPIGENETICS)
hash 3f8a2c…
parent 1b4d7e…
flags 0x10 (EPIGENETICS)
payload {"profile":"compliance","activated_by":"[email protected]"}
sig Ed25519(…)

Python

installation
pip install sapixdb-epigenetics
switch modes and inspect
import asyncio
from sapixdb_epigenetics import EpiClient, EPI_COMPLIANCE, EPI_DEFAULT

async def main():
    async with EpiClient("http://localhost:7475") as epi:
        # Show all available profiles
        all_profiles = await epi.list_profiles()
        for p in all_profiles.profiles:
            writes = "✓" if p.allow_writes else "✗"
            llm    = "✓" if not p.skip_llm  else "✗"
            audit  = "✓" if p.force_audit_on_read else "✗"
            print(f"{p.display_name:<14} writes={writes}  llm={llm}  audit={audit}")

        # Enter compliance mode for a regulated window
        active = await epi.activate(
            EPI_COMPLIANCE,
            activated_by="[email protected]",
            reason="SOC 2 type II audit — 72h window",
        )
        print(f"\nNow active: {active.active}")
        print(f"Audit on read: {active.config.force_audit_on_read}")

        # Quick predicate helpers
        is_restricted = await epi.is_restricted()
        can_write     = await epi.profile_allows_writes()
        print(f"Restricted: {is_restricted}  Can write: {can_write}")

        # Inspect recent switches
        hist = await epi.history()
        for entry in hist.history[-3:]:
            print(f"  {entry.profile:<14} ← {entry.activated_by}")

        # Revert to default
        await epi.activate(EPI_DEFAULT, activated_by="[email protected]")

asyncio.run(main())

EpiClient API

MethodDescription
list_profiles()Return all five built-in profiles with their configurations.
get_profile()Return the currently active profile and activation metadata.
activate(profile, activated_by, reason)Switch the agent to a named profile. Returns 400 for unknown names.
history()Return the last 50 profile activations, oldest first.
is_restricted() → boolTrue if the active profile is anything other than default.
profile_allows_writes() → boolTrue if the current profile permits write operations.
ℹ SapixClient convenience methodsIf you are already using sapixdb-agent, SapixClient exposes thin raw-dict wrappers — epi_profiles(), epi_profile(), epi_activate(profile, activated_by, reason), and epi_history(). Use sapixdb-epigenetics for typed Pydantic models and the higher-level convenience helpers.
Need schema governance too?

Mutants propose schema changes and self-healing actions — governed by the same human approval chain that protects your strands.