File size: 2,856 Bytes
f8b48da | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 | """Content definitions for the AskMyDocs enterprise documentation corpus.
Documents are defined as markdown strings generated by builder functions
that accept a :class:`~scripts.corpus_shims.CorpusContext`, which keeps
cross-references (document ids, usernames, feature flags) consistent.
Sections / topics covered:
docs 001-004 Authentication & security (auth, tokens, mfa, security)
docs 005-009 OAuth / SSO / federation
docs 010-014 API usage / references / errors
docs 015-018 Configuration / feature flags
docs 019-021 Deployment / environments
docs 022-024 Monitoring / observability
docs 025-027 User management / roles
docs 028-031 Database behavior / troubleshooting / rate limits / webhooks
"""
from __future__ import annotations
from collections.abc import Callable
from corpus_shims import front_matter, h2
# ---------------------------------------------------------------------------
# Reusable factual "facts" that the golden dataset references.
# These constants make the golden dataset verifiable against the corpus.
# ---------------------------------------------------------------------------
FACTS = {
"api_key_prefix": "amsk_",
"api_key_lifetime": "90 days",
"oauth_provider": "OAuth 2.0",
"token_expiry": "60 minutes",
"refresh_token_expiry": "30 days",
"rate_limit_default": "100 requests per minute",
"rate_limit_burst": "300 requests per minute",
"webhook_delivery": "HMAC-SHA256 signature",
"webhook_retry": "5 retries, exponential backoff, max 10 minutes",
"database_engine": "PostgreSQL 16",
"db_connection_max": "100",
"backup_retention": "30 days",
"apitoken_claim": "permissions claim",
"rbac_default_role": "viewer",
"sso_saml": "SAML 2.0",
"sso_oidc": "OpenID Connect",
"sla_uptime": "99.95%",
"pii_encryption": "AES-256 at rest",
}
# ---------------------------------------------------------------------------
# Helper: section renderer
# ---------------------------------------------------------------------------
def doc(
doc_id: str,
title: str,
version: str,
module: str,
*sections: Callable[[], str],
) -> str:
"""Compose a document from front matter + sections."""
parts: list[str] = [front_matter(doc_id=doc_id, title=title, version=version, module=module)]
parts.extend(s() for s in sections)
return "\n".join(parts)
def numbered_section(num: int, title: str, body: str) -> str:
return h2(f"{num}. {title}") + body
def create_auth_context() -> dict[str, str]:
"""Context fields shared across auth-related documents."""
return {
"api_key_prefix": FACTS["api_key_prefix"],
"token_expiry": FACTS["token_expiry"],
"refresh_token_expiry": FACTS["refresh_token_expiry"],
} |