orchestrata_ultimate.knowledge_graph.constants

Reference › orchestrata_ultimate › knowledge_graph › constants

Module-level constants for the operational knowledge graph (Spec 008), consumed only by config. The operational graph is the orchkg database on the orchgraph engine (a Memgraph fork). Its URI and database name are deliberately not constants: they were removed in August 2026 because a literal empty-string fallback is forbidden by RUL-003, and callers now resolve them at call time through core.graph_factory.resolve_uri and resolve_kg_database, which raise when the environment key is unset. What remains is the pool size and connection lifetime for Bolt connections (the endpoint negotiates no authentication, so the username and password constants are empty), the three Redis key prefixes under orchestrata:kg for general, cache and sync keys, the per-operation performance targets in milliseconds (PERF_*), and the defaults for synchronization batching, cache size and lifetime, and query depth and limit. Nothing here touches Redis or the graph by itself; the values only feed the dataclasses in config.

At a glance

Class diagram

No classes; see Functions.

Dependency diagram

API

Constants

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/src/orchestrata_ultimate/knowledge_graph/constants.py

"""Knowledge Graph configuration constants."""

# Spec: 008 - Knowledge Graph

# Operational knowledge graph — the `orchkg` database on the orchgraph
# cluster. The URI and target database used to live here as import-time
# constants (``NEO4J_URI`` / ``KG_DATABASE``), each computed via
# ``os.environ.get(..., "")`` — a literal empty-string fallback forbidden by
# RUL-003 (no literal fallback for required infra-connection keys: an unset
# key must RAISE, never silently resolve to "" and then to whatever a Bolt
# driver does with an empty URI/database). They were removed 2026-08-03;
# callers now resolve the URI / database at CALL time via
# ``core.graph_factory.resolve_uri()`` / ``resolve_kg_database()``, which
# raise when the corresponding env key is unset instead of returning "".
#
# No credentials: every remaining graph endpoint negotiates no auth. Renamed
# from NEO4J_USERNAME/NEO4J_PASSWORD in the graph-rename wave (F10) —
# project-owned vocabulary, consistent with GRAPH_USERNAME/GRAPH_PASSWORD
# elsewhere (e.g. tests.infrastructure).
GRAPH_USERNAME: str = ""
GRAPH_PASSWORD: str = ""
GRAPH_MAX_POOL_SIZE: int = 50
GRAPH_MAX_LIFETIME: int = 3600

# Redis key prefixes
REDIS_KG_PREFIX: str = "orchestrata:kg"
REDIS_KG_CACHE_PREFIX: str = "orchestrata:kg:cache"
REDIS_KG_SYNC_PREFIX: str = "orchestrata:kg:sync"

# Performance targets (ms)
PERF_NODE_CREATE_MS: int = 20
PERF_REL_CREATE_MS: int = 10
PERF_SIMPLE_QUERY_MS: int = 50
PERF_COMPLEX_QUERY_MS: int = 200
PERF_PARSE_FILE_MS: int = 500
PERF_SEARCH_MS: int = 100
PERF_TIMELINE_MS: int = 100

# Sync limits
SYNC_BATCH_SIZE: int = 50
SYNC_MAX_FILES: int = 10000
# Wall-clock budget for FileSynchronizer.ensure_fresh (the per-stage
# pre-task hook): on a cold cache (no persisted hash state) every eligible
# file needs a real graph write, so max_files alone does not bound wall
# time. Exceeding this degrades to a partial sync (logged), not a hang.
SYNC_ENSURE_FRESH_DEADLINE_SECONDS: float = 10.0

# Cache settings
CACHE_TTL_SECONDS: float = 300.0
CACHE_MAX_SIZE: int = 1000

# Query limits
QUERY_MAX_DEPTH: int = 10
QUERY_DEFAULT_LIMIT: int = 100