data-olympus 0.3.1__tar.gz → 0.3.2__tar.gz

{data_olympus-0.3.1 → data_olympus-0.3.2}/CHANGELOG.md

@@ -12,6 +12,22 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-07-05
+
+### Fixed
+
+- **`gate/check` no longer self-DoSes multi-agent fleets with 429s.** The
+  enforcement hook calls `POST /api/v1/gate/check` (and `kb_gate_check`) once per
+  gated tool action for every agent, but it shared the write/consult quota
+  (`KB_RATE_LIMIT_PER_HOUR`, default 100). Behind an ingress with no auth, all
+  clients collapse to a single limiter bucket, so a few active agents exhausted
+  the hourly quota in minutes and everything after got `429 Too Many Requests`.
+  gate-check now has its own ceiling, `KB_GATE_CHECK_RATE_LIMIT_PER_HOUR`,
+  defaulting to `0` (unthrottled, consistent with the read routes) since it is a
+  mandatory per-action probe that does only cheap classification and no writes.
+  Set a positive value for an explicit backstop. `consult` and
+  `onboarding/cleanup-plan` stay throttled by `KB_RATE_LIMIT_PER_HOUR`.
+
 ## [0.3.1] - 2026-07-05
 
 ### Fixed
@@ -1013,7 +1029,8 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - `docs/adoption.md`: bring-your-own-KB guide (author, lint, index, serve, wire an agent).
 - `docs/comparison.md`: how data-olympus relates to OKF, enterprise catalogs, markdown KB tools, agent-context conventions, RAG, and ADR tooling.
 
-[Unreleased]: https://github.com/knaisoma/data-olympus/compare/v0.3.1...HEAD
+[Unreleased]: https://github.com/knaisoma/data-olympus/compare/v0.3.2...HEAD
+[0.3.2]: https://github.com/knaisoma/data-olympus/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/knaisoma/data-olympus/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/knaisoma/data-olympus/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/knaisoma/data-olympus/compare/v0.1.1...v0.2.0

{data_olympus-0.3.1 → data_olympus-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: data-olympus
-Version: 0.3.1
+Version: 0.3.2
 Summary: Governance-grade knowledge-base format (OKF-compatible) plus CLI and single-writer MCP server
 Project-URL: Homepage, https://github.com/knaisoma/data-olympus
 Project-URL: Repository, https://github.com/knaisoma/data-olympus

{data_olympus-0.3.1 → data_olympus-0.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "data-olympus"
-version = "0.3.1"
+version = "0.3.2"
 description = "Governance-grade knowledge-base format (OKF-compatible) plus CLI and single-writer MCP server"
 readme = "README.md"
 requires-python = ">=3.13"

{data_olympus-0.3.1 → data_olympus-0.3.2}/src/data_olympus/config.py

@@ -28,6 +28,14 @@ class Config:
     write_block_paths: list[str] = field(default_factory=list)
     rate_limit_per_hour: int = 100
     rate_limit_per_ip_per_hour: int = 0
+    # Separate ceiling for the high-frequency /api/v1/gate/check route (the
+    # enforcement hook's per-tool-action freshness probe). 0 (default) disables
+    # throttling for that route: it is a mandatory, once-per-tool-call, read-only
+    # probe, so any fixed hourly quota self-DoSes an active multi-agent fleet
+    # (behind ingress all clients collapse to one limiter bucket). Reads are
+    # already unthrottled; this keeps gate/check consistent with them. Set a
+    # positive value only if you want an explicit backstop.
+    gate_check_rate_limit_per_hour: int = 0
     max_text_bytes: int = 262144
     max_postimage_bytes: int = 1048576
     max_body_bytes: int = 2097152
@@ -155,6 +163,7 @@ def load_config() -> Config:
     write_block_paths = _split_csv(os.getenv("KB_WRITE_BLOCK_PATHS", ""))
     rate_limit_per_hour = int(os.getenv("KB_RATE_LIMIT_PER_HOUR", "100"))
     rate_limit_per_ip_per_hour = int(os.getenv("KB_RATE_LIMIT_PER_IP_PER_HOUR", "0"))
+    gate_check_rate_limit_per_hour = int(os.getenv("KB_GATE_CHECK_RATE_LIMIT_PER_HOUR", "0"))
     max_text_bytes = int(os.getenv("KB_MAX_TEXT_BYTES", "262144"))
     max_postimage_bytes = int(os.getenv("KB_MAX_POSTIMAGE_BYTES", "1048576"))
     max_body_bytes = int(os.getenv("KB_MAX_BODY_BYTES", "2097152"))
@@ -226,6 +235,7 @@ def load_config() -> Config:
         write_block_paths=write_block_paths,
         rate_limit_per_hour=rate_limit_per_hour,
         rate_limit_per_ip_per_hour=rate_limit_per_ip_per_hour,
+        gate_check_rate_limit_per_hour=gate_check_rate_limit_per_hour,
         max_text_bytes=max_text_bytes,
         max_postimage_bytes=max_postimage_bytes,
         max_body_bytes=max_body_bytes,

{data_olympus-0.3.1 → data_olympus-0.3.2}/src/data_olympus/rest_api.py

@@ -32,6 +32,7 @@ if TYPE_CHECKING:
     from starlette.requests import Request
 
     from data_olympus.models import HealthResponse
+    from data_olympus.rate_limit import SlidingWindowLimiter
     from data_olympus.server import ServerState
 
 
@@ -285,22 +286,33 @@ async def _read_json_capped(
         )
 
 
+_USE_WRITE_LIMITER: Any = object()
+
+
 def _rate_limited(
     state: ServerState, request: Request, principal: Principal,
+    *, limiter: SlidingWindowLimiter | None = _USE_WRITE_LIMITER,
 ) -> JSONResponse | None:
-    """Apply the shared sliding-window limiter to an enforcement-plane route.
-
-    The consult / gate / cleanup-plan routes were previously unthrottled (item 6),
-    so an anonymous or authenticated caller could hammer the classifier and ledger
-    without bound. Reuse the same limiter the write routes use, keyed by
-    (remote_addr, principal name) so a per-principal quota applies. Returns a 429
-    JSONResponse when over quota, else None.
-
-    When the limiter is absent (a read-only deployment with no write pipeline
-    configured) throttling is skipped: there is no shared limiter object to
-    consult and these routes are read-mostly there.
+    """Apply a sliding-window limiter to an enforcement-plane route.
+
+    The consult / cleanup-plan routes were previously unthrottled (item 6), so an
+    anonymous or authenticated caller could hammer the classifier and ledger
+    without bound. They reuse the write limiter (``state.rate_limiter``), keyed by
+    (remote_addr, principal name). Returns a 429 JSONResponse when over quota, else
+    None.
+
+    ``limiter`` overrides which limiter to consult. The high-frequency
+    /api/v1/gate/check route passes ``state.gate_rate_limiter`` (None by default),
+    so it is unthrottled unless an operator sets an explicit ceiling: it is a
+    mandatory once-per-tool-action probe, and any fixed quota shared across a
+    fleet (all clients collapse to one bucket behind ingress) self-DoSes with 429s.
+
+    When the resolved limiter is absent (a read-only deployment, or gate/check with
+    no ceiling configured) throttling is skipped.
     """
-    limiter = state.rate_limiter
+    # Distinguish "no limiter arg" (use the write limiter) from an explicit None
+    # (the gate-check limiter with no ceiling: throttling is genuinely off).
+    limiter = state.rate_limiter if limiter is _USE_WRITE_LIMITER else limiter
     if limiter is None:
         return None
     remote_addr = request.client.host if request.client else "unknown"
@@ -662,7 +674,12 @@ def register_routes(
             principal, denied = _authorize(request, registry)
             if denied is not None:
                 return denied
-            if (throttled := _rate_limited(state, request, principal)) is not None:
+            # gate/check uses its own limiter (unthrottled by default): it is the
+            # hook's once-per-tool-action probe, so it must not share the write /
+            # consult quota (that self-DoSes a fleet, see _rate_limited).
+            if (throttled := _rate_limited(
+                state, request, principal, limiter=state.gate_rate_limiter
+            )) is not None:
                 return throttled
             import time as _time
 

{data_olympus-0.3.1 → data_olympus-0.3.2}/src/data_olympus/server.py

@@ -123,6 +123,7 @@ class ServerState:
         push_queue: PushQueue | None = None,
         pending: PendingQueue | None = None,
         rate_limiter: SlidingWindowLimiter | None = None,
+        gate_rate_limiter: SlidingWindowLimiter | None = None,
         blocklist: PathBlocklist | None = None,
         audit_log: AuditLog | None = None,
         classifier: IntentClassifier | None = None,
@@ -147,6 +148,10 @@ class ServerState:
         self.push_queue: PushQueue | None = push_queue
         self.pending: PendingQueue | None = pending
         self.rate_limiter: SlidingWindowLimiter | None = rate_limiter
+        # Separate limiter for /api/v1/gate/check (None = unthrottled, the default).
+        # Kept distinct from `rate_limiter` so gate-check traffic and the write /
+        # consult / cleanup-plan quota never share a bucket.
+        self.gate_rate_limiter: SlidingWindowLimiter | None = gate_rate_limiter
         self.blocklist: PathBlocklist | None = blocklist
         self.audit_log: AuditLog | None = audit_log
         # Process-wide write serializer (scope item 1): one instance shared by
@@ -232,6 +237,7 @@ def build_app(
     confidence_threshold: float = 0.85,
     rate_limit_per_hour: int = 100,
     rate_limit_per_ip_per_hour: int = 0,
+    gate_check_rate_limit_per_hour: int = 0,
     max_text_bytes: int = 262144,
     max_postimage_bytes: int = 1048576,
     max_body_bytes: int = 2097152,
@@ -279,6 +285,7 @@ def build_app(
         write_block_paths=write_block_paths or [],
         rate_limit_per_hour=rate_limit_per_hour,
         rate_limit_per_ip_per_hour=rate_limit_per_ip_per_hour,
+        gate_check_rate_limit_per_hour=gate_check_rate_limit_per_hour,
         max_text_bytes=max_text_bytes,
         max_postimage_bytes=max_postimage_bytes,
         max_body_bytes=max_body_bytes,
@@ -393,6 +400,13 @@ def build_app(
             max_per_hour=config.rate_limit_per_hour,
             max_per_ip_per_hour=config.rate_limit_per_ip_per_hour,
         )
+        # gate/check gets its own limiter only when a positive ceiling is set;
+        # 0 (default) leaves it unthrottled (see Config.gate_check_rate_limit_per_hour).
+        gate_rate_limiter = (
+            SlidingWindowLimiter(max_per_hour=config.gate_check_rate_limit_per_hour)
+            if config.gate_check_rate_limit_per_hour > 0
+            else None
+        )
         blocklist = PathBlocklist(
             tier_blocks=config.write_block_tiers,
             path_blocks=config.write_block_paths,
@@ -401,6 +415,7 @@ def build_app(
         state.push_queue = push_queue
         state.pending = pending
         state.rate_limiter = rate_limiter
+        state.gate_rate_limiter = gate_rate_limiter
         state.blocklist = blocklist
 
     if config.kb_remote_url and not config.read_only:
@@ -545,17 +560,22 @@ def build_app(
         )
         return resp.model_dump()
 
-    def _mcp_rate_limited() -> dict[str, object] | None:
-        """Apply the shared sliding-window limiter to an MCP enforcement-plane tool
+    def _mcp_rate_limited(*, gate: bool = False) -> dict[str, object] | None:
+        """Apply a sliding-window limiter to an MCP enforcement-plane tool
         (WP0b item (b)).
 
-        The REST consult / gate-check / cleanup-plan routes throttle via
-        ``_rate_limited``; the MCP tool paths did not, so an agent could hammer the
-        classifier/ledger unbounded. Key on the resolved principal (there is no
-        per-request remote addr on the MCP transport, so the limiter's per-agent
-        quota is the meaningful dimension). Returns a rejection dict when over
-        quota, else None. Skipped when no limiter is wired (read-only deploy)."""
-        limiter = state.rate_limiter
+        The REST consult / cleanup-plan routes throttle via ``_rate_limited``; the
+        MCP tool paths did not, so an agent could hammer the classifier/ledger
+        unbounded. Key on the resolved principal (there is no per-request remote
+        addr on the MCP transport, so the limiter's per-agent quota is the
+        meaningful dimension). Returns a rejection dict when over quota, else None.
+
+        ``gate=True`` (kb_gate_check) consults ``state.gate_rate_limiter`` instead
+        of the write limiter; that limiter is None by default, so the
+        high-frequency freshness probe is unthrottled unless explicitly capped,
+        matching the REST /api/v1/gate/check route. Skipped when the resolved
+        limiter is None (read-only deploy, or gate-check with no ceiling set)."""
+        limiter = state.gate_rate_limiter if gate else state.rate_limiter
         if limiter is None:
             return None
         principal_name = _current_principal.get().name
@@ -768,7 +788,7 @@ def build_app(
         ) -> dict[str, object]:
             """Return a verdict (allow | consult_required) for a pending code action.
             Governed actions require a fresh consultation on record."""
-            if (throttled := _mcp_rate_limited()) is not None:
+            if (throttled := _mcp_rate_limited(gate=True)) is not None:
                 return throttled
             import time as _time
 
@@ -852,6 +872,7 @@ def build_app_from_config(config: Config, *, bootstrap_now: bool = True) -> Fast
         confidence_threshold=config.confidence_threshold,
         rate_limit_per_hour=config.rate_limit_per_hour,
         rate_limit_per_ip_per_hour=config.rate_limit_per_ip_per_hour,
+        gate_check_rate_limit_per_hour=config.gate_check_rate_limit_per_hour,
         max_text_bytes=config.max_text_bytes,
         max_postimage_bytes=config.max_postimage_bytes,
         max_body_bytes=config.max_body_bytes,