kevlar-agent 0.1.0__tar.gz

kevlar_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KiitaInternet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kevlar_agent-0.1.0/PACKAGE_README.md

@@ -0,0 +1,101 @@
+# kevlar-agent
+
+Reliability primitives for AI agents that have to survive real use — extracted
+from a voice AI assistant that has run continuously, unattended, in production.
+Zero dependencies (an optional one for the watchdog). MIT licensed.
+
+**[Why this exists / the full case study →](https://kiitainternet.github.io/kevlar/)**
+
+```bash
+pip install kevlar-agent
+```
+
+## The six primitives
+
+```python
+from kevlar_agent import dedupe, budget_guard, require_confirmation, silent, AuditLog, Watchdog
+```
+
+### `dedupe` — suppress duplicate calls
+
+```python
+@dedupe(window_seconds=5)
+def launch_session(device_id: str) -> str:
+    return f"launched {device_id}"
+```
+
+An identical call within the window is skipped instead of running the side
+effect twice — fixes the "model emitted the same tool call twice" class of bug.
+
+### `budget_guard` — independent per-feature spend ceilings
+
+```python
+@budget_guard("image_gen", monthly_limit_usd=3.0, cost_usd=0.04)
+def generate_clip(prompt: str) -> str:
+    ...
+```
+
+Raises `BudgetExceeded` before the call runs if this *specific feature* would
+go over its own monthly ceiling — even if ten other features share the same
+underlying API key.
+
+### `require_confirmation` — code-enforced consent for irreversible actions
+
+```python
+@require_confirmation(lambda amount: f"transfer ${amount}")
+def transfer(amount: float) -> str:
+    ...
+
+transfer(50)                    # raises ConfirmationRequired
+transfer(50, confirmed=True)    # runs
+```
+
+A prompt-only guardrail is a suggestion the model can miss. This one is a gate.
+
+### `silent` — call anything with a hard timeout, from any thread
+
+```python
+try:
+    token = silent(refresh_oauth_token, timeout_seconds=15)
+except SilentTimeout:
+    token = None  # fail fast instead of hanging forever
+```
+
+Fixes the "OAuth helper opened a browser and waited for a click that never
+came, because nobody was watching" class of bug.
+
+### `AuditLog` — structured, append-only call log
+
+```python
+log = AuditLog("logs/audit")
+log.record("send_email", {"to": "x@example.com"}, result="sent", source="voice")
+log.tail(limit=20)
+```
+
+One JSON object per line, one file per day. Never raises.
+
+### `Watchdog` — restart what dies
+
+```python
+from kevlar_agent.watchdog import Watched
+
+wd = Watchdog([
+    Watched("telegram_bot.py", start=["python", "telegram_bot.py"]),
+    Watched("mobile_relay.py", start=["python", "mobile_relay.py"]),
+])
+wd.run_forever(interval_seconds=300)
+```
+
+Liveness checking uses `psutil` by default (`pip install kevlar-agent[watchdog]`),
+or pass your own `is_alive` callable.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

kevlar_agent-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: kevlar-agent
+Version: 0.1.0
+Summary: Reliability primitives for AI agents that have to survive real use: dedupe, budget guards, silent-timeout, audit trails, confirmation gates, and a self-supervising watchdog.
+Author: KiitaInternet
+License: MIT
+Project-URL: Homepage, https://kiitainternet.github.io/kevlar/
+Project-URL: Repository, https://github.com/KiitaInternet/kevlar
+Keywords: ai,agent,reliability,llm,tool-calling,watchdog,production
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: watchdog
+Requires-Dist: psutil>=5.9; extra == "watchdog"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: psutil>=5.9; extra == "dev"
+Dynamic: license-file
+
+# kevlar-agent
+
+Reliability primitives for AI agents that have to survive real use — extracted
+from a voice AI assistant that has run continuously, unattended, in production.
+Zero dependencies (an optional one for the watchdog). MIT licensed.
+
+**[Why this exists / the full case study →](https://kiitainternet.github.io/kevlar/)**
+
+```bash
+pip install kevlar-agent
+```
+
+## The six primitives
+
+```python
+from kevlar_agent import dedupe, budget_guard, require_confirmation, silent, AuditLog, Watchdog
+```
+
+### `dedupe` — suppress duplicate calls
+
+```python
+@dedupe(window_seconds=5)
+def launch_session(device_id: str) -> str:
+    return f"launched {device_id}"
+```
+
+An identical call within the window is skipped instead of running the side
+effect twice — fixes the "model emitted the same tool call twice" class of bug.
+
+### `budget_guard` — independent per-feature spend ceilings
+
+```python
+@budget_guard("image_gen", monthly_limit_usd=3.0, cost_usd=0.04)
+def generate_clip(prompt: str) -> str:
+    ...
+```
+
+Raises `BudgetExceeded` before the call runs if this *specific feature* would
+go over its own monthly ceiling — even if ten other features share the same
+underlying API key.
+
+### `require_confirmation` — code-enforced consent for irreversible actions
+
+```python
+@require_confirmation(lambda amount: f"transfer ${amount}")
+def transfer(amount: float) -> str:
+    ...
+
+transfer(50)                    # raises ConfirmationRequired
+transfer(50, confirmed=True)    # runs
+```
+
+A prompt-only guardrail is a suggestion the model can miss. This one is a gate.
+
+### `silent` — call anything with a hard timeout, from any thread
+
+```python
+try:
+    token = silent(refresh_oauth_token, timeout_seconds=15)
+except SilentTimeout:
+    token = None  # fail fast instead of hanging forever
+```
+
+Fixes the "OAuth helper opened a browser and waited for a click that never
+came, because nobody was watching" class of bug.
+
+### `AuditLog` — structured, append-only call log
+
+```python
+log = AuditLog("logs/audit")
+log.record("send_email", {"to": "x@example.com"}, result="sent", source="voice")
+log.tail(limit=20)
+```
+
+One JSON object per line, one file per day. Never raises.
+
+### `Watchdog` — restart what dies
+
+```python
+from kevlar_agent.watchdog import Watched
+
+wd = Watchdog([
+    Watched("telegram_bot.py", start=["python", "telegram_bot.py"]),
+    Watched("mobile_relay.py", start=["python", "mobile_relay.py"]),
+])
+wd.run_forever(interval_seconds=300)
+```
+
+Liveness checking uses `psutil` by default (`pip install kevlar-agent[watchdog]`),
+or pass your own `is_alive` callable.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

kevlar_agent-0.1.0/README.md

@@ -0,0 +1,46 @@
+# KEVLAR
+
+**A case study in what it actually takes to keep a voice-driven AI agent running, unattended, for months.**
+
+Most agent frameworks optimize for the demo: wire up a tool, watch it call an API, ship it. KEVLAR is the opposite kind of artifact — a single-page write-up of the reliability patterns that only show up after an agent has been left running against real usage, real API quotas, and real unattended background jobs long enough for the unglamorous failure modes to surface.
+
+**[Live case study →](https://kiitainternet.github.io/kevlar/)** · **[`pip install kevlar-agent`](./PACKAGE_README.md)** — the six patterns below, as a real, tested, installable library.
+
+## Why this exists
+
+Every pattern documented on the page traces back to a real failure, not a hypothetical one:
+
+- An OAuth helper that opened a browser and waited for a human click — called from a background thread with no human anywhere near it. It hung for hours.
+- Two rapid duplicate tool calls in the same turn that spun up two concurrent live sessions on the same device.
+- One shared API key silently starving a second feature of quota mid-conversation because nothing isolated their spend.
+
+None of that shows up in a framework's quickstart. It only shows up in production, after enough real hours logged. This page is what that experience distilled into reusable patterns looks like.
+
+## What's here
+
+A single self-contained `index.html` — no build step, no dependencies, no framework. Open it in a browser or drop it on any static host.
+
+- An original, hand-authored animated HUD visual (Canvas 2D — no external asset, no template)
+- Six documented reliability patterns, each with the failure mode that motivated it
+- A system-shape diagram showing how one audited dispatch core serves multiple front-end channels
+- A simulated self-check terminal sequence
+
+## Stack
+
+**The case study page**: plain HTML/CSS/JS, Google Fonts (Orbitron, Rajdhani, IBM Plex Sans, JetBrains Mono). No frameworks, no bundler, no build step — intentionally, so anyone can read the entire implementation top to bottom in one file.
+
+**The library** (`kevlar_agent/`): zero-dependency Python (one optional dependency, `psutil`, for the watchdog's default liveness check). 24 tests, all passing — see [PACKAGE_README.md](./PACKAGE_README.md) for usage.
+
+```bash
+pip install kevlar-agent
+```
+
+```bash
+# to run the test suite yourself
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

kevlar_agent-0.1.0/kevlar_agent/__init__.py

@@ -0,0 +1,37 @@
+"""
+KEVLAR — reliability primitives for AI agents that have to survive real use.
+
+Six small, dependency-free utilities, each extracted from a real production
+failure in an always-on voice AI assistant:
+
+    dedupe               suppress duplicate calls within a time window
+    budget_guard         per-feature monthly spend ceiling
+    require_confirmation enforce an explicit confirm flag for risky actions
+    silent(...)          run a blocking/interactive call with a hard timeout
+    AuditLog             structured, append-only call log (JSONL)
+    Watchdog             supervise external processes, restart what dies
+
+None of this is clever. All of it is necessary once something runs
+unattended long enough for the boring failure modes to show up.
+"""
+
+from .dedupe import dedupe
+from .budget import BudgetExceeded, budget_guard
+from .confirm import ConfirmationRequired, require_confirmation
+from .silent import SilentTimeout, silent
+from .audit import AuditLog
+from .watchdog import Watchdog
+
+__all__ = [
+    "dedupe",
+    "budget_guard",
+    "BudgetExceeded",
+    "require_confirmation",
+    "ConfirmationRequired",
+    "silent",
+    "SilentTimeout",
+    "AuditLog",
+    "Watchdog",
+]
+
+__version__ = "0.1.0"

kevlar_agent-0.1.0/kevlar_agent/audit.py

@@ -0,0 +1,94 @@
+"""
+Full-fidelity audit trail for tool/agent calls.
+
+Real failure this fixes: without a record of what was actually called,
+with what arguments, from where, and whether it errored, "it worked when
+I tested it" is the only signal available — and that signal lies. The
+audit log is what revealed, after the fact, that a background scheduler
+was silently calling the same five "safe" tools every day while a dozen
+others had never been exercised outside manual testing.
+
+Deliberately boring: append-only JSONL, one file per day, no external
+dependencies. Never raises — a logging failure must not take down the
+call it's trying to record.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+
+class AuditLog:
+    """Append-only, structured call log — one JSON object per line, per day.
+
+    Example:
+        >>> log = AuditLog("logs/audit")
+        >>> log.record("send_email", {"to": "x@example.com"}, result="sent", source="voice")
+        >>> recent = log.tail(limit=10)
+    """
+
+    def __init__(self, directory: str | Path):
+        self.directory = Path(directory)
+
+    def _file_for_today(self) -> Path:
+        return self.directory / f"{time.strftime('%Y-%m-%d')}.jsonl"
+
+    def record(
+        self,
+        tool: str,
+        args: Any = None,
+        *,
+        result: Any = None,
+        error: str | None = None,
+        duration_ms: float | None = None,
+        source: str = "default",
+    ) -> None:
+        """Append one call record. Never raises, even if the write itself fails."""
+        try:
+            self.directory.mkdir(parents=True, exist_ok=True)
+            row = {
+                "ts": time.strftime("%Y-%m-%d %H:%M:%S"),
+                "source": source,
+                "tool": tool,
+                "args": _safe_str(args),
+                "result": _safe_str(result),
+                "error": error,
+                "duration_ms": round(duration_ms, 1) if duration_ms is not None else None,
+            }
+            with open(self._file_for_today(), "a", encoding="utf-8") as f:
+                f.write(json.dumps(row, ensure_ascii=False) + "\n")
+        except Exception:
+            pass  # a logging failure must never break the caller
+
+    def tail(self, limit: int = 50, tool: str | None = None) -> list[dict]:
+        """Return the most recent records, newest first, optionally filtered by tool name."""
+        if not self.directory.exists():
+            return []
+        out: list[dict] = []
+        for path in sorted(self.directory.glob("*.jsonl"), reverse=True):
+            for line in reversed(path.read_text(encoding="utf-8").splitlines()):
+                try:
+                    row = json.loads(line)
+                except Exception:
+                    continue
+                if tool and row.get("tool") != tool:
+                    continue
+                out.append(row)
+                if len(out) >= limit:
+                    return out
+        return out
+
+
+def _safe_str(value: Any, max_chars: int = 2000) -> str | None:
+    if value is None:
+        return None
+    try:
+        text = value if isinstance(value, str) else json.dumps(value, ensure_ascii=False, default=str)
+    except Exception:
+        return "<unserializable>"
+    if len(text) > max_chars:
+        return text[:max_chars] + f"...(truncated {len(text) - max_chars} chars)"
+    return text

kevlar_agent-0.1.0/kevlar_agent/budget.py

@@ -0,0 +1,115 @@
+"""
+Per-feature budget guards.
+
+Real failure this fixes: two features shared one provider API key with
+no spend isolation. A usage spike in one feature silently starved the
+other of quota mid-conversation — nobody could tell which feature was
+actually responsible until the audit log was cross-referenced by hand.
+
+The fix: every paid call declares which "feature" it belongs to and how
+much it costs, and gets checked against that feature's own monthly
+ceiling — independent of every other feature, even if they share the
+same underlying API key.
+"""
+
+from __future__ import annotations
+
+import functools
+import json
+import time
+from pathlib import Path
+from typing import Any, Callable, TypeVar
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class BudgetExceeded(Exception):
+    """Raised when a feature's monthly spend ceiling would be exceeded."""
+
+    def __init__(self, feature: str, spent: float, limit: float):
+        self.feature = feature
+        self.spent = spent
+        self.limit = limit
+        super().__init__(
+            f"'{feature}' has spent ${spent:.2f} of its ${limit:.2f}/month budget"
+        )
+
+
+class _Ledger:
+    """Tracks spend per feature per calendar month, persisted to a small JSON file."""
+
+    def __init__(self, storage_path: str | Path):
+        self.path = Path(storage_path)
+
+    def _month_key(self) -> str:
+        return time.strftime("%Y-%m")
+
+    def _load(self) -> dict:
+        if not self.path.exists():
+            return {}
+        try:
+            return json.loads(self.path.read_text(encoding="utf-8"))
+        except Exception:
+            return {}
+
+    def _save(self, data: dict) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+    def spent(self, feature: str) -> float:
+        return self._load().get(feature, {}).get(self._month_key(), 0.0)
+
+    def add(self, feature: str, amount: float) -> float:
+        data = self._load()
+        month = self._month_key()
+        data.setdefault(feature, {})
+        data[feature][month] = data[feature].get(month, 0.0) + amount
+        self._save(data)
+        return data[feature][month]
+
+
+def budget_guard(
+    feature: str,
+    *,
+    monthly_limit_usd: float,
+    cost_usd: float | Callable[..., float],
+    storage_path: str | Path = ".kevlar_budget.json",
+) -> Callable[[F], F]:
+    """Enforce an independent monthly spend ceiling for one named feature.
+
+    Args:
+        feature: a stable name for the thing being metered (e.g. "image_gen").
+            Two decorators with different ``feature`` names never share a budget,
+            even if they hit the same paid API underneath.
+        monthly_limit_usd: the ceiling for this feature, this calendar month.
+        cost_usd: either a fixed cost per call, or a callable that receives the
+            same ``(*args, **kwargs)`` as the wrapped function and returns the
+            cost for that specific call (use this when cost varies by input,
+            e.g. token count or output length).
+        storage_path: where running spend is persisted between calls/restarts.
+
+    Raises:
+        BudgetExceeded: if this call would push the feature over its ceiling.
+            The wrapped function is never invoked in that case.
+
+    Example:
+        >>> @budget_guard("image_gen", monthly_limit_usd=3.0, cost_usd=0.04)
+        ... def generate_clip(prompt: str) -> str:
+        ...     return f"generated: {prompt}"
+    """
+    ledger = _Ledger(storage_path)
+
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            call_cost = cost_usd(*args, **kwargs) if callable(cost_usd) else cost_usd
+            spent = ledger.spent(feature)
+            if spent + call_cost > monthly_limit_usd:
+                raise BudgetExceeded(feature, spent, monthly_limit_usd)
+            result = func(*args, **kwargs)
+            ledger.add(feature, call_cost)
+            return result
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator

kevlar_agent-0.1.0/kevlar_agent/confirm.py

@@ -0,0 +1,66 @@
+"""
+Confirmation enforced as code, not as a prompt.
+
+Real failure this fixes: a system prompt politely asked the model to
+"confirm before doing anything irreversible." The model occasionally
+skipped that step anyway — not maliciously, just a misread of intent.
+A polite instruction is a suggestion; it is not a gate.
+
+The fix: wrap the risky function itself. It refuses to run unless the
+caller passes ``confirmed=True`` explicitly. There is no code path that
+reaches the real side effect without that flag being true — the model
+(or any caller) cannot talk its way past it.
+"""
+
+from __future__ import annotations
+
+import functools
+from typing import Any, Callable, TypeVar
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class ConfirmationRequired(Exception):
+    """Raised when a guarded action is called without confirmed=True."""
+
+    def __init__(self, summary: str):
+        self.summary = summary
+        super().__init__(f"confirmation required: {summary}")
+
+
+def require_confirmation(summary: str | Callable[..., str]) -> Callable[[F], F]:
+    """Refuse to run the wrapped function unless called with ``confirmed=True``.
+
+    Args:
+        summary: a human-readable description of what's about to happen, or a
+            callable that builds one from the call's ``(*args, **kwargs)``.
+            Surfaced on :class:`ConfirmationRequired` so the caller (e.g. an
+            agent loop) can relay it back to a human and ask for real consent.
+
+    The ``confirmed`` kwarg is consumed by this decorator and never forwarded
+    to the wrapped function.
+
+    Example:
+        >>> @require_confirmation(lambda amount: f"transfer ${amount}")
+        ... def transfer(amount: float, confirmed: bool = False) -> str:
+        ...     return f"transferred ${amount}"
+        >>> transfer(50)
+        Traceback (most recent call last):
+            ...
+        kevlar_agent.confirm.ConfirmationRequired: confirmation required: transfer $50
+        >>> transfer(50, confirmed=True)
+        'transferred $50'
+    """
+
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            confirmed = kwargs.pop("confirmed", False)
+            if not confirmed:
+                text = summary(*args, **kwargs) if callable(summary) else summary
+                raise ConfirmationRequired(text)
+            return func(*args, **kwargs)
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator

kevlar_agent-0.1.0/kevlar_agent/dedupe.py

@@ -0,0 +1,69 @@
+"""
+Duplicate-call suppression.
+
+Real failure this fixes: an LLM emitted the same tool call twice in one
+turn (an eager first pass, then a retry). Both calls launched a live
+session on the same device — two overlapping audio streams, one user.
+
+The fix is deliberately dumb: hash the function name + its arguments,
+remember the last time that exact call happened, and skip the real work
+if it happened again inside the window. The *caller* still gets a
+return value (so the agent loop doesn't see an error) — it's just a
+cached "already done" response instead of doing the side effect twice.
+"""
+
+from __future__ import annotations
+
+import functools
+import json
+import time
+from typing import Any, Callable, TypeVar
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+_last_seen: dict[str, float] = {}
+
+
+def _call_key(func: Callable, args: tuple, kwargs: dict) -> str:
+    try:
+        payload = json.dumps({"args": args, "kwargs": kwargs}, sort_keys=True, default=str)
+    except TypeError:
+        payload = repr((args, kwargs))
+    return f"{func.__module__}.{func.__qualname__}:{payload}"
+
+
+def dedupe(window_seconds: float = 5.0, *, on_duplicate: Any = None) -> Callable[[F], F]:
+    """Suppress a second call with identical args within ``window_seconds``.
+
+    Args:
+        window_seconds: how long an identical call is considered a duplicate.
+        on_duplicate: value to return when a duplicate is caught. If it's
+            callable, it's invoked with the same ``(*args, **kwargs)`` the
+            original call received; otherwise it's returned as-is. Defaults
+            to ``None``.
+
+    Example:
+        >>> @dedupe(window_seconds=5)
+        ... def launch_session(device_id: str) -> str:
+        ...     return f"launched {device_id}"
+        >>> launch_session("phone-1")
+        'launched phone-1'
+        >>> launch_session("phone-1")  # within 5s: skipped, no second launch
+    """
+
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            key = _call_key(func, args, kwargs)
+            now = time.monotonic()
+            last = _last_seen.get(key)
+            if last is not None and (now - last) < window_seconds:
+                if callable(on_duplicate):
+                    return on_duplicate(*args, **kwargs)
+                return on_duplicate
+            _last_seen[key] = now
+            return func(*args, **kwargs)
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator