TealTemporal

pip install tealtiger

import asyncio
from tealtiger.temporal import TealTemporal

temporal = TealTemporal(
    session={
        "enabled": True,
        "default_ttl": "8h",
        "max_ttl": "24h",
        "on_expiry": "deny",
    },
    cooldown={
        "enabled": True,
        "rules": [
            {"action": "payment.refund", "cooldown": "5m", "scope": "per_agent"},
            {"action": "file.delete", "cooldown": "30s", "scope": "per_agent", "max_per_window": {"count": 5, "window": "1h"}},
        ],
        "on_violation": "deny",
    },
    time_restrictions={
        "enabled": True,
        "timezone": "America/New_York",
        "rules": [
            {
                "name": "business-hours-only",
                "actions": ["payment.*", "deployment.*"],
                "allowed_windows": [
                    {"days": ["mon", "tue", "wed", "thu", "fri"], "start": "09:00", "end": "17:00"}
                ],
            }
        ],
        "on_violation": "deny",
    },
)

async def main():
    decision = await temporal.evaluate(
        request={"action": "payment.refund", "session_id": "sess-abc"},
        ctx={"agent_id": "support-bot-001", "correlation_id": "req-001"},
    )

    print(decision.allowed)            # True or False
    print(decision.session_valid)      # True
    print(decision.cooldown_active)    # False
    print(decision.time_window_valid)  # True

asyncio.run(main())

class TealTemporal:
    def __init__(
        self,
        session: dict | None = None,
        cooldown: dict | None = None,
        time_restrictions: dict | None = None,
    ) -> None: ...

    async def evaluate(self, request: dict, ctx: dict) -> TemporalDecision: ...

    async def check_session(self, agent_id: str, session_id: str) -> SessionStatus: ...

    async def record_action(self, agent_id: str, action: str) -> None: ...

    async def get_cooldown(self, agent_id: str, action: str) -> CooldownStatus: ...

status = await temporal.check_session("agent-001", "sess-abc")
print(status.valid)           # True
print(status.remaining_ttl)   # "2h 15m"
print(status.expires_at)      # "2026-06-01T16:00:00Z"

# After expiry:
expired = await temporal.check_session("agent-001", "sess-abc")
print(expired.valid)   # False
print(expired.reason)  # "SESSION_TTL_EXPIRED"

# First refund — allowed
await temporal.record_action("agent-001", "payment.refund")

# Immediate retry — check cooldown
cooldown = await temporal.get_cooldown("agent-001", "payment.refund")
print(cooldown.active)          # True
print(cooldown.remaining_time)  # "4m 58s"
print(cooldown.next_allowed)    # "2026-06-01T14:35:00Z"

temporal = TealTemporal(
    cooldown={
        "enabled": True,
        "rules": [
            {
                "action": "file.delete",
                "cooldown": "30s",
                "scope": "per_agent",
                "max_per_window": {"count": 5, "window": "1h"},
            }
        ],
        "on_violation": "deny",
    },
)

# After 5 deletes in the current hour:
cooldown = await temporal.get_cooldown("agent-001", "file.delete")
print(cooldown.actions_in_window)  # 5
print(cooldown.max_in_window)      # 5
# Next file.delete will be denied

temporal = TealTemporal(
    time_restrictions={
        "enabled": True,
        "timezone": "America/New_York",
        "rules": [
            {
                "name": "business-hours-only",
                "actions": ["payment.*", "database.migrate"],
                "allowed_windows": [
                    {"days": ["mon", "tue", "wed", "thu", "fri"], "start": "09:00", "end": "17:00"}
                ],
            },
            {
                "name": "no-deployments-friday-afternoon",
                "actions": ["deployment.*"],
                "denied_windows": [
                    {"days": ["fri"], "start": "14:00", "end": "23:59"}
                ],
            },
        ],
        "on_violation": "deny",
    },
)

# At 3 PM on Friday:
decision = await temporal.evaluate(
    request={"action": "deployment.production"},
    ctx={"agent_id": "deploy-bot", "correlation_id": "req-001"},
)

# decision.allowed == False
# decision.violations == ["TIME_RESTRICTION_VIOLATED"]
# decision.details["time_window"]["next_allowed"] == "Mon 09:00 ET"

from dataclasses import dataclass

@dataclass
class TemporalDecision:
    allowed: bool                  # All temporal constraints pass
    violations: list[str]          # Which constraints were violated
    session_valid: bool            # Session validity check
    cooldown_active: bool          # Whether a cooldown is blocking
    time_window_valid: bool        # Current time within allowed window
    details: dict                  # Per-constraint details

@dataclass
class SessionStatus:
    valid: bool
    remaining_ttl: str | None
    started_at: str
    expires_at: str
    reason: str | None             # "SESSION_TTL_EXPIRED" | "SESSION_REVOKED"
    in_grace_period: bool

@dataclass
class CooldownStatus:
    active: bool
    remaining_time: str | None
    next_allowed: str | None
    actions_in_window: int | None
    max_in_window: int | None

from tealtiger import TealEngine, TealTemporal

engine = TealEngine(
    policy={
        "temporal": {
            "session": {"default_ttl": "8h", "max_ttl": "24h", "on_expiry": "deny"},
            "cooldown": {
                "rules": [{"action": "payment.*", "cooldown": "5m", "scope": "per_agent"}]
            },
            "time_restrictions": {
                "timezone": "UTC",
                "rules": [
                    {"name": "business-hours", "actions": ["payment.*"], "allowed_windows": [{"days": ["mon", "tue", "wed", "thu", "fri"], "start": "08:00", "end": "18:00"}]}
                ],
            },
        }
    },
    modules=[TealTemporal(
        session={"enabled": True, "default_ttl": "8h", "max_ttl": "24h", "on_expiry": "deny"},
        cooldown={"enabled": True, "rules": [{"action": "payment.*", "cooldown": "5m", "scope": "per_agent"}], "on_violation": "deny"},
        time_restrictions={"enabled": True, "timezone": "UTC", "rules": [], "on_violation": "deny"},
    )],
)