Q&A: ExplainAPI configuration and deployment

[web3guru888]

Frequently asked questions — ExplainAPI (#283)

This thread collects anticipated configuration and deployment questions for Phase 8.3.

---

Q1: How do I generate and rotate API keys?

build_explain_app() accepts api_keys: frozenset[str].
Load keys from environment variables or a secret manager at startup:

import os
keys = frozenset(filter(None, os.environ.get("EXPLAIN_API_KEYS", "").split(",")))
app = build_explain_app(tracer=tracer, graph=graph, api_keys=keys)

To rotate: update the env var and restart the process (or add hot-reload logic by
passing a mutable set wrapped in a callable dependency).

---

Q2: What rate_limit_rps value should I start with?

Deployment context	Recommended RPS
Single-operator dashboard	5–10
CI test harness	100+
Multi-team monitoring	20 (default)
Public / untrusted clients	2–5 + IP allowlist

The burst capacity equals rate_limit_rps (1 second of tokens).
If you see frequent 429s from legitimate clients, increase the value or implement
client-side exponential backoff.

---

Q3: What does GET /traces?limit=200 cost in memory?

The InMemoryTraceStorage from Phase 8.1 uses a deque with maxlen=buffer_capacity.
Reading a snapshot is O(N) where N = min(buffer_capacity, limit).

buffer_capacity	Max memory (est.)
1 000	~2 MB
10 000	~20 MB
100 000	~200 MB

/traces always returns ≤ 200 items regardless of buffer size. If you need more,
use since pagination:

GET /traces?limit=200&since=0           # first 200 oldest
GET /traces?limit=200&since=<last_ts>   # next page

---

Q4: Can I query the graph while a CognitiveCycle tick is running?

Yes — CausalGraph uses asyncio.Lock internally.
GET /graph/snapshot acquires the lock briefly to copy state; it will block for at
most one add_edge() call duration (microseconds), then release.
There is no long-held read lock — snapshot is a point-in-time copy.

---

Q5: How should I handle GET /graph/ancestors/{id} with deep DAGs?

The max_depth parameter (default 10, max 50) prevents runaway BFS on large graphs.
For Phase 8 cognitive graphs, practical depths are:

Scenario	Expected depth
Single CognitiveCycle tick	5–10 nodes
Multi-phase accumulated graph	15–30 nodes
Long-running agent (hours)	50–200+ nodes

For deep graphs, use max_depth=50 and paginate by re-querying from the deepest
ancestor returned (using its ID as the new starting node_id).

---

Q6: How do I mount ExplainApp alongside an existing aiohttp server?

Use uvicorn with the FastAPI app directly, or mount it as a sub-app:

# Mount ExplainApp on a sub-path with Starlette
from starlette.applications import Starlette
from starlette.routing import Mount

root_app = Starlette(routes=[
    Mount("/explain", app=explain_app),
    # ... other routes
])

Or run as a standalone service on a separate port (recommended for production isolation).

---

Q7: How do I monitor ExplainAPI health with Prometheus alerts?

Three recommended alerting rules:

# High error rate (>5% of requests are 4xx/5xx)
- alert: ExplainAPIHighErrorRate
  expr: |
    rate(explain_api_requests_total{status=~"4..|5.."}[5m]) /
    rate(explain_api_requests_total[5m]) > 0.05

# Sustained rate limiting (clients hitting 429)
- alert: ExplainAPIRateLimiting
  expr: increase(explain_api_rate_limited_total[5m]) > 10

# Slow responses (p99 > 500ms)
- alert: ExplainAPISlowResponses
  expr: |
    histogram_quantile(0.99,
      rate(explain_api_request_duration_seconds_bucket[5m])
    ) > 0.5