boundedllm 0.4.0__py3-none-any.whl

boundedllm/__init__.py

@@ -0,0 +1,86 @@
+"""Deterministic security boundaries for enterprise LLM applications.
+
+Importing this package starts no servers, reads no credentials, and pulls in no
+database driver. The core depends on the storage contracts in
+``boundedllm.ports``; a host implements them over whatever it already runs, or
+imports ``boundedllm.adapters.sql`` for a working implementation.
+
+    from boundedllm import Audit, Guard, Limits
+    from boundedllm.adapters.sql import SQLStore, sql_ports
+
+    audit = Audit(key)
+    store = SQLStore(settings, audit)
+    guard = Guard(provider=provider, signer=audit, **sql_ports(store))
+
+What this package is for: bounding what a compromised agent can reach and do.
+Identity, tenant isolation, retrieval ACLs, tool authorization, human consent,
+idempotency, quotas, and a tamper-evident ledger are deterministic application
+code here, and they hold whether or not the model has been manipulated.
+
+What it is not: a prompt-injection detector. ``boundedllm.risk`` is a tripwire for
+blunt override attempts, and the bundled ``PatternScanner`` is a test baseline,
+not a DLP product. Both are signals. The boundaries above are the controls.
+"""
+
+__version__ = "0.4.0"
+
+from boundedllm.audit import Audit
+from boundedllm.engine import Guard
+from boundedllm.errors import (
+    Conflict,
+    Denied,
+    GuardError,
+    InvalidToken,
+    LimitExceeded,
+    OutputBlocked,
+    Unavailable,
+)
+from boundedllm.limits import Limits
+from boundedllm.model_gateway import ModelProvider, ModelRequest
+from boundedllm.models import (
+    ChatRequest,
+    ChatResponse,
+    Document,
+    IngestRequest,
+    Principal,
+    ProposedToolCall,
+    ToolExecutionResult,
+    TurnFlags,
+)
+from boundedllm.output_firewall import Scanner
+from boundedllm.ports import Documents, Ledger, Operations, Quotas, Signer
+from boundedllm.telemetry import Observability, OpenTelemetryObservability
+from boundedllm.tool_gateway import ToolExecutor
+
+__all__ = [
+    "Audit",
+    "ChatRequest",
+    "ChatResponse",
+    "Conflict",
+    "Denied",
+    "Document",
+    "Documents",
+    "Guard",
+    "GuardError",
+    "IngestRequest",
+    "InvalidToken",
+    "Ledger",
+    "LimitExceeded",
+    "Limits",
+    "ModelProvider",
+    "ModelRequest",
+    "Observability",
+    "OpenTelemetryObservability",
+    "Operations",
+    "OutputBlocked",
+    "Principal",
+    "ProposedToolCall",
+    "Quotas",
+    "Scanner",
+    "Signer",
+    "ToolExecutionResult",
+    "ToolExecutor",
+    "TurnFlags",
+    "Unavailable",
+    "__version__",
+]

boundedllm/adapters/__init__.py

@@ -0,0 +1,6 @@
+"""Concrete implementations of the core ports and provider contracts.
+
+Everything here is optional. The core depends on ``boundedllm.ports``; these
+modules depend on SQLAlchemy, httpx, and deployment configuration, which is why
+they are kept off the core import path.
+"""

boundedllm/adapters/http_model.py

@@ -0,0 +1,45 @@
+"""A generic HTTPS model transport for deployments without a vendor SDK.
+
+Kept out of the core so importing ``boundedllm`` costs no HTTP client and no
+deployment configuration. A host that already uses a vendor SDK should implement
+``ModelProvider`` against it directly rather than route through this contract.
+"""
+
+import httpx
+
+from boundedllm.config import Settings
+from boundedllm.errors import Unavailable
+from boundedllm.model_gateway import ModelRequest
+from boundedllm.network import bounded_json
+
+
+class HTTPModelProvider:
+    """Generic enterprise endpoint contract, not a vendor-specific API implementation."""
+
+    def __init__(self, settings: Settings, client: httpx.AsyncClient):
+        if not settings.model_url:
+            raise ValueError("model_url required")
+        self.settings = settings
+        self.client = client
+
+    async def complete(self, request: ModelRequest) -> str:
+        headers = {}
+        if self.settings.model_api_key:
+            headers["Authorization"] = "Bearer " + self.settings.model_api_key.get_secret_value()
+        data = await bounded_json(
+            self.client,
+            "POST",
+            self.settings.model_url,
+            max_bytes=131072,
+            headers=headers,
+            json={
+                "model": request.model,
+                "system": request.system,
+                "user": request.user,
+                "max_output_tokens": request.max_output_tokens,
+                "temperature": 0,
+            },
+        )
+        if set(data) != {"text"} or not isinstance(data["text"], str):
+            raise Unavailable("MODEL_RESPONSE_SCHEMA")
+        return data["text"]

boundedllm/adapters/otlp.py

@@ -0,0 +1,104 @@
+"""At-least-once delivery of signed ledger records to an OTLP/HTTP collector.
+
+The request path writes the ledger and its outbox in one database transaction.
+This worker drains that outbox and marks records exported only after the
+collector acknowledges them, so a delivery failure never loses evidence and a
+retry never loses a record. Collectors and SIEMs deduplicate on ``event_id``.
+
+Kept out of the core because it needs an HTTP client and a concrete store.
+"""
+
+import json
+import time
+from typing import Protocol
+
+import httpx
+
+from boundedllm.adapters.sql.store import SQLStore
+from boundedllm.config import require_https
+
+
+class SecurityEventSink(Protocol):
+    """Small adapter surface for an OTel Collector or enterprise SIEM gateway."""
+
+    def export(self, events: list[dict]) -> None: ...
+
+
+class OpenTelemetryHTTPSink:
+    """Send metadata-only events using OTLP/HTTP JSON to ``/v1/logs``."""
+
+    def __init__(self, endpoint: str, authorization: str | None = None):
+        self.endpoint = require_https(endpoint)
+        self.authorization = authorization
+
+    def export(self, events: list[dict]) -> None:
+        if not events:
+            return
+        records = []
+        for envelope in events:
+            payload = json.loads(envelope["payload"])
+            attributes = [
+                {"key": "security.event_id", "value": {"stringValue": envelope["event_id"]}},
+                {"key": "security.tenant_id", "value": {"stringValue": envelope["tenant_id"]}},
+                {"key": "security.sequence", "value": {"intValue": str(envelope["sequence"])}},
+                {"key": "security.record_hash", "value": {"stringValue": envelope["record_hash"]}},
+                {"key": "security.key_id", "value": {"stringValue": envelope["key_id"]}},
+            ]
+            records.append(
+                {
+                    "timeUnixNano": str(int(payload["timestamp"] * 1_000_000_000)),
+                    "observedTimeUnixNano": str(time.time_ns()),
+                    "severityText": str(payload.get("severity", "INFO")).upper(),
+                    "body": {"stringValue": envelope["payload"]},
+                    "attributes": attributes,
+                }
+            )
+        body = {
+            "resourceLogs": [
+                {
+                    "resource": {
+                        "attributes": [
+                            {
+                                "key": "service.name",
+                                "value": {"stringValue": "boundedllm"},
+                            }
+                        ]
+                    },
+                    "scopeLogs": [
+                        {
+                            "scope": {"name": "boundedllm.audit"},
+                            "logRecords": records,
+                        }
+                    ],
+                }
+            ]
+        }
+        headers = {"Content-Type": "application/json"}
+        if self.authorization:
+            headers["Authorization"] = self.authorization
+        with httpx.Client(
+            timeout=httpx.Timeout(15, connect=5),
+            follow_redirects=False,
+            trust_env=False,
+        ) as client:
+            with client.stream("POST", self.endpoint, headers=headers, json=body) as response:
+                response.raise_for_status()
+                received = 0
+                for chunk in response.iter_bytes():
+                    received += len(chunk)
+                    if received > 65536:
+                        raise ValueError("OTLP acknowledgement exceeded 64 KiB")
+
+
+def export_pending(store: SQLStore, tenant_id: str, sink: SecurityEventSink, limit: int = 100) -> int:
+    """Deliver one bounded batch and acknowledge its exact hashes after success."""
+    events = store.pending_audit_exports(tenant_id, limit)
+    if not events:
+        return 0
+    try:
+        sink.export(events)
+    except Exception:
+        store.mark_audit_export_failed(tenant_id, events)
+        raise
+    store.mark_audit_exported(tenant_id, events)
+    return len(events)

boundedllm/adapters/sql/__init__.py

@@ -0,0 +1,136 @@
+"""Batteries-included SQL implementation of every core port.
+
+Use this when you want the package to own its storage. A host that already has a
+document store, an audit pipeline, or an authorization service should implement
+``boundedllm.ports`` against those instead; nothing in the core knows this module
+exists.
+
+The store is synchronous SQLAlchemy, so this adapter is where the threading
+policy lives. Every call crosses into a worker thread through
+``asyncio.to_thread``, which means the default executor's thread count is the
+real concurrency ceiling for database work. Raise it deliberately for a
+high-throughput deployment:
+
+    import asyncio, concurrent.futures
+    loop = asyncio.get_running_loop()
+    loop.set_default_executor(concurrent.futures.ThreadPoolExecutor(max_workers=64))
+
+Putting that decision here, rather than in the request path, is the point of the
+port boundary: swapping in an async driver changes this file and nothing else.
+"""
+
+import asyncio
+from pathlib import Path
+
+from boundedllm.adapters.sql.schema import metadata
+from boundedllm.adapters.sql.store import SQLStore
+from boundedllm.models import ChatRequest, ChatResponse, Document, Principal, RequestContext
+
+ALEMBIC_INI = Path(__file__).with_name("alembic.ini")
+
+__all__ = ["ALEMBIC_INI", "SQLAdapter", "SQLStore", "metadata", "migrate", "sql_ports", "stamp"]
+
+
+def _alembic_config():
+    from alembic.config import Config
+
+    config = Config(str(ALEMBIC_INI))
+    # script_location resolves against the ini's own directory so migrations are
+    # found inside an installed wheel, not just in a source checkout.
+    config.set_main_option("script_location", str(ALEMBIC_INI.parent / "migrations"))
+    return config
+
+
+def migrate(revision: str = "head") -> None:
+    """Run versioned migrations against GUARD_DATABASE_URL.
+
+    This is the production path. ``SQLStore.initialize`` is a development
+    convenience that creates tables directly and leaves no reviewable history,
+    which is not something a DBA team will accept on a real database.
+    """
+    from alembic import command
+
+    command.upgrade(_alembic_config(), revision)
+
+
+def stamp(revision: str = "head") -> None:
+    """Record a revision without running it, for a database created before Alembic."""
+    from alembic import command
+
+    command.stamp(_alembic_config(), revision)
+
+
+class SQLAdapter:
+    """Implements Ledger, Quotas, Operations, and Documents over one SQL store."""
+
+    def __init__(self, store: SQLStore):
+        self.store = store
+
+    # Ledger ---------------------------------------------------------------
+    async def event(self, ctx: RequestContext, event: str, **fields) -> None:
+        await asyncio.to_thread(self.store.event, ctx, event, **fields)
+
+    # Quotas ---------------------------------------------------------------
+    async def throttle(self, principal: Principal) -> None:
+        await asyncio.to_thread(self.store.throttle, principal)
+
+    async def reserve_model_cost(self, ctx: RequestContext) -> None:
+        await asyncio.to_thread(self.store.reserve_model_cost, ctx)
+
+    # Operations -----------------------------------------------------------
+    async def claim(self, ctx: RequestContext, request: ChatRequest) -> ChatResponse | None:
+        return await asyncio.to_thread(self.store.claim_operation, ctx, request)
+
+    async def finish(
+        self,
+        ctx: RequestContext,
+        operation_id: str,
+        response: ChatResponse | None,
+        docs: list[Document] | None = None,
+    ) -> None:
+        await asyncio.to_thread(self.store.finish_operation, ctx, operation_id, response, docs)
+
+    # Documents ------------------------------------------------------------
+    async def search(
+        self,
+        principal: Principal,
+        query: str,
+        limit: int,
+        max_level: int,
+        conversation_id: str,
+        attachment_ids: list[str],
+    ) -> list[Document]:
+        return await asyncio.to_thread(
+            self.store.search, principal, query, limit, max_level, conversation_id, attachment_ids
+        )
+
+    async def quarantine(self, ctx: RequestContext, doc_id: str, signals: list[str]) -> None:
+        await asyncio.to_thread(self.store.quarantine_document, ctx, doc_id, signals)
+
+    async def attachment_results(
+        self, principal: Principal, conversation_id: str, attachment_ids: list[str]
+    ) -> list[dict]:
+        return await asyncio.to_thread(
+            self.store.attachment_results, principal, conversation_id, attachment_ids
+        )
+
+    # Convenience used by host tool executors, which are async by contract.
+    async def get_account(self, principal: Principal, account_id: str):
+        return await asyncio.to_thread(self.store.get_account, principal, account_id)
+
+    async def propose_waiver(self, ctx, request, args, flags, policy) -> dict:
+        return await asyncio.to_thread(self.store.propose_waiver, ctx, request, args, flags, policy)
+
+
+def sql_ports(store: SQLStore) -> dict:
+    """Spread into ``Guard(...)`` so one adapter satisfies every port by name.
+
+    guard = Guard(provider=provider, signer=audit, **sql_ports(store))
+    """
+    adapter = SQLAdapter(store)
+    return {
+        "ledger": adapter,
+        "quotas": adapter,
+        "operations": adapter,
+        "documents": adapter,
+    }

boundedllm/adapters/sql/alembic.ini

@@ -0,0 +1,39 @@
+# The database URL is resolved from GUARD_DATABASE_URL in env.py, never here, so
+# this file carries no credentials and is safe to ship inside the wheel.
+[alembic]
+script_location = %(here)s/migrations
+prepend_sys_path = .
+file_template = %%(year)d%%(month).2d%%(day).2d_%%(rev)s_%%(slug)s
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARNING
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARNING
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s

boundedllm/adapters/sql/migrations/env.py

@@ -0,0 +1,59 @@
+"""Alembic environment for the bundled SQL adapter.
+
+The database URL comes from ``GUARD_DATABASE_URL`` through ``Settings`` so a
+migration run cannot be pointed somewhere the application itself would refuse,
+and so the URL never has to be written into a config file in the repository.
+
+Importing the support schema registers the reference domain's tables on the same
+MetaData. A deployment that does not use that domain can remove the import; its
+tables are then absent from autogenerate and from the migration history.
+"""
+
+from alembic import context
+from sqlalchemy import engine_from_config, pool
+
+import boundedllm.support.schema  # noqa: F401  registers the reference domain tables
+from boundedllm.adapters.sql.schema import metadata
+from boundedllm.config import Settings
+
+config = context.config
+target_metadata = metadata
+
+
+def _url() -> str:
+    return Settings().database_url.get_secret_value()
+
+
+def run_migrations_offline() -> None:
+    context.configure(
+        url=_url(),
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+        compare_type=True,
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    section = config.get_section(config.config_ini_section, {})
+    section["sqlalchemy.url"] = _url()
+    connectable = engine_from_config(section, prefix="sqlalchemy.", poolclass=pool.NullPool)
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata,
+            compare_type=True,
+            # SQLite cannot ALTER most columns in place; batch mode rewrites the
+            # table instead so the same revision runs on the demo and on Postgres.
+            render_as_batch=connection.dialect.name == "sqlite",
+        )
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

boundedllm/adapters/sql/migrations/script.py.mako

@@ -0,0 +1,24 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = ${repr(up_revision)}
+down_revision: str | None = ${repr(down_revision)}
+branch_labels: str | Sequence[str] | None = ${repr(branch_labels)}
+depends_on: str | Sequence[str] | None = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}