orchestrata_ultimate.knowledge_graph.config

Reference › orchestrata_ultimate › knowledge_graph › config

Runtime configuration for the operational knowledge graph, the orchkg database on the orchgraph engine (a Memgraph fork). Five dataclasses hold it: GraphClientConfig (Bolt URI, database, pool size, connection lifetime and a 30-second connection timeout), CacheConfig (TTL and maximum size), SyncConfig (batch size, file cap, the ensure-fresh deadline, watch interval, debounce, the watched extensions .py and .pl, and ignore patterns), QueryConfig (maximum depth and default limit) and the top-level KnowledgeGraphConfig that composes them and adds the Redis host, port and database number.

The URI and database use default factories, resolve_uri and resolve_kg_database from core.graph_factory, and the Redis host and port use resolve_redis_host and resolve_redis_port. Under RUL-003 these raise when their environment key (for example REDIS_HOST and REDIS_PORT) is unset instead of falling back to a literal, so constructing a config in an unconfigured environment fails loudly. redis_db reads REDIS_DB and defaults to 0. The remaining defaults come from constants. The classes are traced to Specs 001 and 008. graph_client, file_watcher, the kernel pipeline CLI and the architect volk context import it.

At a glance

Class diagram

Dependency diagram

API

Classes

GraphClientConfig (dataclass)

Decorators: dataclass, traces(spec='001', story='US-010', reqs=['REQ-001-US-010-013']) · Line 40

Graph connection configuration.

CacheConfig (dataclass)

Decorators: dataclass, traces(spec='008', story='US-003', reqs=['REQ-008-015']) · Line 54

Cache configuration.

SyncConfig (dataclass)

Decorators: dataclass, traces(spec='008', story='US-005', reqs=['REQ-008-026']) · Line 63

File synchronization configuration.

QueryConfig (dataclass)

Decorators: dataclass, traces(spec='008', story='US-006', reqs=['REQ-008-039']) · Line 86

Query engine configuration.

KnowledgeGraphConfig (dataclass)

Decorators: dataclass · Line 94

Top-level configuration for the knowledge graph module.

Source

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

"""Knowledge Graph runtime configuration."""

# Spec: 008 - Knowledge Graph

import os
from dataclasses import dataclass, field

from orchestrata_ultimate.core.base.traces import traces
from orchestrata_ultimate.core.graph_factory import resolve_kg_database, resolve_uri
from orchestrata_ultimate.core.redis_factory import (
    resolve_redis_host,
    resolve_redis_port,
)
from orchestrata_ultimate.knowledge_graph.constants import (
    CACHE_MAX_SIZE,
    CACHE_TTL_SECONDS,
    GRAPH_MAX_LIFETIME,
    GRAPH_MAX_POOL_SIZE,
    GRAPH_PASSWORD,
    GRAPH_USERNAME,
    QUERY_DEFAULT_LIMIT,
    QUERY_MAX_DEPTH,
    SYNC_BATCH_SIZE,
    SYNC_ENSURE_FRESH_DEADLINE_SECONDS,
    SYNC_MAX_FILES,
)

# The ``uri`` / ``database`` fields below used to resolve through local
# ``_default_uri()`` / ``_default_database()`` helpers that re-implemented
# the KG_ROUTING_URI/KG_URI/KG_DATABASE resolution chain with a literal ""
# fallback (via the now-removed ``constants.NEO4J_URI`` / ``KG_DATABASE``) —
# forbidden by RUL-003 (no literal fallback for required infra-connection
# keys). ``core.graph_factory.resolve_uri`` / ``resolve_kg_database`` are
# the canonical seam: same per-construction (not import-time) resolution,
# but RAISE when the key is unset instead of silently returning "".


@dataclass
@traces(spec="001", story="US-010", reqs=["REQ-001-US-010-013"])
class GraphClientConfig:
    """Graph connection configuration."""

    uri: str = field(default_factory=resolve_uri)
    username: str = GRAPH_USERNAME
    password: str = GRAPH_PASSWORD
    database: str = field(default_factory=resolve_kg_database)
    max_pool_size: int = GRAPH_MAX_POOL_SIZE
    max_connection_lifetime: int = GRAPH_MAX_LIFETIME
    connection_timeout: int = 30


@dataclass
@traces(spec="008", story="US-003", reqs=["REQ-008-015"])
class CacheConfig:
    """Cache configuration."""

    ttl_seconds: float = CACHE_TTL_SECONDS
    max_size: int = CACHE_MAX_SIZE


@dataclass
@traces(spec="008", story="US-005", reqs=["REQ-008-026"])
class SyncConfig:
    """File synchronization configuration."""

    batch_size: int = SYNC_BATCH_SIZE
    max_files: int = SYNC_MAX_FILES
    ensure_fresh_deadline_seconds: float = SYNC_ENSURE_FRESH_DEADLINE_SECONDS
    watch_interval: float = 5.0
    debounce_seconds: float = 2.0
    watch_extensions: set[str] = field(default_factory=lambda: {".py", ".pl"})
    ignore_patterns: list[str] = field(
        default_factory=lambda: [
            "__pycache__",
            ".git",
            ".venv",
            "node_modules",
            "*.pyc",
            "*.pyo",
        ]
    )


@dataclass
@traces(spec="008", story="US-006", reqs=["REQ-008-039"])
class QueryConfig:
    """Query engine configuration."""

    max_depth: int = QUERY_MAX_DEPTH
    default_limit: int = QUERY_DEFAULT_LIMIT


@dataclass
class KnowledgeGraphConfig:
    """Top-level configuration for the knowledge graph module."""

    graph: GraphClientConfig = field(default_factory=GraphClientConfig)
    cache: CacheConfig = field(default_factory=CacheConfig)
    sync: SyncConfig = field(default_factory=SyncConfig)
    query: QueryConfig = field(default_factory=QueryConfig)
    # No literal fallback (RUL-003): resolve_redis_host/port RAISE when
    # REDIS_HOST/REDIS_PORT is unset rather than silently defaulting to
    # localhost:6379.
    redis_host: str = field(default_factory=resolve_redis_host)
    redis_port: int = field(default_factory=resolve_redis_port)
    redis_db: int = int(os.environ.get("REDIS_DB", "0"))