TealState

pip install tealtiger

import asyncio
from tealtiger.state import TealState

state = TealState(
    size_governance={
        "enabled": True,
        "max_tokens": 8192,
        "warning_threshold": 0.8,
        "on_exceeded": "deny",
    },
    provenance={
        "enabled": True,
        "require_source": True,
        "trust_levels": {
            "system": "trusted",
            "user": "verified",
            "tool_output": "verified",
            "web_search": "unverified",
            "agent_generated": "unverified",
        },
    },
)

async def main():
    decision = await state.evaluate_mutation(
        mutation={
            "type": "add",
            "entry": {
                "id": "ctx-entry-001",
                "content": "Customer account balance: $4,521.00",
                "source": "tool_output",
                "tool": "account_lookup",
                "tokens": 12,
                "priority": "high",
                "ttl": "30m",
            },
        },
        ctx={
            "agent_id": "support-bot-001",
            "correlation_id": "req-001",
            "current_context_tokens": 6000,
        },
    )

    print(decision.allowed)           # True
    print(decision.new_context_size)  # 6012 tokens
    print(decision.budget_remaining)  # 2180 tokens

asyncio.run(main())

class TealState:
    def __init__(
        self,
        size_governance: dict | None = None,
        provenance: dict | None = None,
        ttl: dict | None = None,
        mutations: dict | None = None,
    ) -> None: ...

    async def evaluate_mutation(
        self,
        mutation: dict,
        ctx: dict,
    ) -> MutationDecision: ...

    async def get_context_budget(self, agent_id: str) -> ContextBudget: ...

    async def get_provenance(self, entry_id: str) -> ProvenanceRecord: ...

    async def audit_context(self, agent_id: str) -> ContextAudit: ...

state = TealState(
    size_governance={
        "enabled": True,
        "max_tokens": 8192,
        "warning_threshold": 0.8,
        "on_exceeded": "truncate_lowest_priority",  # "deny" | "truncate_oldest" | "truncate_lowest_priority"
    },
    provenance={
        "enabled": True,
        "require_source": True,
        "trust_levels": {
            "system": "trusted",
            "user": "verified",
            "tool_output": "verified",
            "web_search": "unverified",
            "agent_generated": "unverified",
        },
    },
    ttl={
        "enabled": True,
        "default_ttl": "1h",
        "by_source": {
            "web_search": "15m",
            "tool_output": "30m",
            "user": "24h",
        },
    },
    mutations={
        "require_justification": False,
        "max_entries": 200,
        "allowed_mutations": ["add", "update", "remove"],
    },
)

# Context at 95% capacity — new entry arrives
decision = await state.evaluate_mutation(
    mutation={
        "type": "add",
        "entry": {"content": "...", "tokens": 500, "priority": "medium"},
    },
    ctx={"agent_id": "bot-001", "current_context_tokens": 7800},
)

# With "truncate_lowest_priority":
# decision.allowed == True
# decision.evicted == ["ctx-entry-old-1", "ctx-entry-old-2"]
# decision.new_context_size == 7200 (after eviction + addition)

from dataclasses import dataclass

@dataclass
class ProvenanceRecord:
    entry_id: str
    source: str
    trust_level: str       # "trusted" | "verified" | "unverified" | "untrusted"
    added_at: str
    added_by: str
    tool: str | None
    correlation_id: str
    content_hash: str
    expires_at: str | None
    modifications: list[dict]

prov = await state.get_provenance("ctx-entry-001")
print(prov.source)       # "tool_output"
print(prov.trust_level)  # "verified"
print(prov.tool)         # "account_lookup"

budget = await state.get_context_budget("support-bot-001")

print(budget.max_tokens)        # 8192
print(budget.used_tokens)       # 6012
print(budget.remaining_tokens)  # 2180
print(budget.utilization_pct)   # 73.4
print(budget.warning)           # False (below 80% threshold)
print(budget.entries)           # 42

audit = await state.audit_context("support-bot-001")

print(audit.total_entries)       # 42
print(audit.total_tokens)        # 6012
print(audit.by_trust_level)      # {"trusted": 5, "verified": 30, "unverified": 7}
print(audit.expiring_soon)       # 3 entries expiring within 5 minutes
print(audit.untrusted_entries)   # Entries from untrusted sources

from tealtiger import TealEngine, TealState

engine = TealEngine(
    policy={
        "state": {
            "size_governance": {"enabled": True, "max_tokens": 8192, "on_exceeded": "deny"},
            "provenance": {"enabled": True, "require_source": True},
            "ttl": {"enabled": True, "default_ttl": "1h"},
        }
    },
    modules=[TealState(
        size_governance={"enabled": True, "max_tokens": 8192, "warning_threshold": 0.8, "on_exceeded": "deny"},
        provenance={"enabled": True, "require_source": True, "trust_levels": {"system": "trusted", "user": "verified"}},
    )],
)