contextsynapse 1.0.0__py3-none-any.whl

contextsynapse/config/context_presets/toi_politics.json

@@ -0,0 +1,25 @@
+{
+  "name": "TOI Politics & Economy",
+  "description": "Indian political and economic news from Times of India",
+  "context_type": "knowledge_base",
+  "sensitivity": "public",
+  "tags": ["news", "india", "politics"],
+  "pipeline": {
+    "template_id": "builtin:smart-article",
+    "source_url": "https://timesofindia.indiatimes.com/",
+    "max_pages": 5,
+    "schema_id": "news_article",
+    "schema_mode": "schema_plus"
+  },
+  "filters": {
+    "keyword_exclude": ["cricket", "bollywood", "horoscope", "recipe"],
+    "keyword_include": ["politics", "economy", "policy", "parliament", "budget", "RBI"],
+    "semantic_rules": [
+      {"description": "Indian government policy decisions and legislation", "threshold": 0.7},
+      {"description": "Economic reforms, GDP, inflation, and RBI monetary policy", "threshold": 0.6},
+      {"description": "Elections, political parties, and campaign news", "threshold": 0.65}
+    ],
+    "semantic_mode": "or"
+  },
+  "schedule": {"trigger_type": "scheduled", "interval_minutes": 60}
+}

contextsynapse/config/database_config.py

@@ -0,0 +1,453 @@
+"""
+Database Configuration Manager
+
+Centralized configuration system similar to PostgreSQL (postgresql.conf), 
+MySQL (my.cnf), MongoDB (mongod.conf), etc.
+
+Supports:
+- Performance tuning
+- Storage configuration
+- Connection settings
+- Logging configuration
+- Feature flags
+"""
+
+import json
+import yaml
+import logging
+from pathlib import Path
+from typing import Dict, Any, Optional, Union
+from dataclasses import dataclass, asdict
+from enum import Enum
+
+logger = logging.getLogger(__name__)
+
+
+class ConfigFormat(Enum):
+    """Supported configuration formats."""
+    YAML = "yaml"
+    JSON = "json"
+    INI = "ini"
+
+
+@dataclass
+class PerformanceConfig:
+    """Performance tuning parameters."""
+    # Graph Database Settings (moved from config/config.yaml)
+    default_engine: str = "csr"  # Graph engine: csr (NetworkX disabled - CSR-only mode)
+    auto_index: bool = True  # Enable automatic indexing
+    cache_size: int = 1000  # Cache size (number of items)
+    
+    # Graph operations
+    max_nodes_in_memory: int = 1000000  # Max nodes before spilling to disk
+    max_edges_in_memory: int = 5000000  # Max edges before spilling to disk
+    cache_size_mb: int = 512  # Cache size in MB
+    enable_query_cache: bool = True  # Enable query result caching
+    
+    # CSR settings
+    csr_auto_switch_threshold: int = 1000  # Switch to CSR at this node count
+    csr_enabled: bool = True  # Enable CSR storage
+    
+    # Buffer settings (for delayed block updates)
+    buffer_enabled: bool = True  # Enable buffer manager for batch writes
+    buffer_type: str = "local"  # Buffer backend: local, file, redis, sqlite, duckdb, lmdb
+    buffer_max_size: int = 1000  # Max records before auto-flush
+    buffer_flush_interval: float = 2.0  # Seconds between auto-flushes (delayed block update)
+    buffer_batch_size: int = 100  # Records per batch when flushing
+    buffer_auto_flush: bool = True  # Enable automatic flushing
+    buffer_flush_threshold: float = 0.7  # Flush when buffer reaches 70% capacity (0.0-1.0)
+    buffer_threshold_flush_enabled: bool = True  # Enable threshold-based flushing
+    
+    # Vector operations
+    vector_batch_size: int = 1000  # Batch size for vector operations
+    vector_index_type: str = "flat"  # FAISS index type: flat, ivf, hnsw
+    
+    # Parallel processing
+    max_workers: int = 4  # Max parallel workers
+    enable_parallel_queries: bool = True  # Enable parallel query execution
+    
+    # Memory management
+    gc_threshold: int = 10000  # Garbage collection threshold
+    enable_auto_gc: bool = True  # Automatic garbage collection
+    
+    # WAL (Write-Ahead Logging) Configuration - Neo4j-level performance
+    wal_enabled: bool = True  # Enable WAL for fast writes (Neo4j-style)
+    wal_dir: str = "./contextcore_wal"  # WAL directory
+    wal_max_size_mb: int = 100  # Max WAL size before rotation (MB)
+    wal_checkpoint_interval: int = 1000  # Checkpoint every N operations
+    wal_sync_interval: float = 1.0  # Sync to disk every N seconds
+    wal_compression: bool = True  # Enable WAL compression
+    wal_background_flush: bool = True  # Background flush to main graph file
+    
+    # Persistence Performance Optimization
+    persistence_mode: str = "wal"  # Options: "wal" (fast, recommended), "direct" (fallback)
+    background_save_threshold: int = 10000  # Use background save for graphs > N nodes
+    immediate_persistence: bool = True  # Neo4j-style immediate persistence
+
+
+@dataclass
+class StorageConfig:
+    """Storage configuration."""
+    # Storage strategy
+    storage_strategy: str = "single_file"  # Options: "single_file" (HDF5), "multi_file_optimized" (format-specific)
+    storage_format: str = "single_file"  # Deprecated: use storage_strategy instead
+    storage_type: str = "hdf5"  # json, hdf5, parquet (default: hdf5 for single-file)
+    
+    # Compression
+    compression_enabled: bool = True
+    compression_level: int = 6  # 0-9, higher = more compression
+    
+    # Persistence
+    auto_save: bool = True  # Auto-save on changes
+    auto_save_interval: int = 300  # Auto-save interval in seconds
+    save_on_shutdown: bool = True  # Save on graceful shutdown
+    
+    # Backup
+    backup_enabled: bool = True
+    backup_retention_days: int = 30  # Keep backups for N days
+    backup_location: str = "contextcore_data/backups"
+    
+    # Node properties
+    node_properties_format: str = "parquet"  # json, parquet
+    node_properties_compression: str = "snappy"  # snappy, gzip, lz4
+    
+    # CSR storage
+    csr_save_enabled: bool = True
+    csr_load_priority: bool = True  # Try CSR first on load
+
+
+@dataclass
+class ConnectionConfig:
+    """Connection and API settings."""
+    # API server
+    api_host: str = "0.0.0.0"
+    api_port: int = 8000
+    api_workers: int = 1  # Single process — agents connect from their own platforms
+    
+    # Timeouts
+    request_timeout: int = 300  # Request timeout in seconds
+    session_timeout: int = 3600  # Session timeout in seconds
+    
+    # Rate limiting
+    rate_limit_enabled: bool = False
+    rate_limit_per_minute: int = 1000
+    
+    # CORS
+    cors_enabled: bool = True
+    cors_origins: list = None  # None = allow all
+    
+    def __post_init__(self):
+        if self.cors_origins is None:
+            self.cors_origins = ["*"]
+
+
+@dataclass
+class LoggingConfig:
+    """Logging configuration."""
+    # Log levels
+    log_level: str = "INFO"  # DEBUG, INFO, WARNING, ERROR, CRITICAL
+    log_file: Optional[str] = None  # None = console only
+    log_format: str = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+    log_date_format: str = "%Y-%m-%d %H:%M:%S"
+    
+    # Log rotation
+    log_rotation_enabled: bool = True
+    log_max_bytes: int = 10485760  # 10 MB
+    log_backup_count: int = 5
+    
+    # Component-specific logging
+    log_queries: bool = True  # Log all queries
+    log_performance: bool = False  # Log performance metrics
+    log_storage_ops: bool = False  # Log storage operations
+
+
+@dataclass
+class SecurityConfig:
+    """Security settings."""
+    # Authentication
+    auth_enabled: bool = False
+    auth_method: str = "token"  # token, oauth, basic
+    
+    # Encryption
+    encryption_enabled: bool = False
+    encryption_key: Optional[str] = None
+    
+    # Access control
+    access_control_enabled: bool = False
+    default_role: str = "user"  # admin, user, readonly
+
+
+@dataclass
+class TraceabilityConfig:
+    """Traceability/Blockchain configuration."""
+    enabled: bool = True  # Enable blockchain/traceability layer
+    batch_size: int = 100  # Commit Merkle root every N operations
+    auto_commit: bool = True  # Auto-commit batches
+    verify_on_read: bool = False  # Verify integrity on read (performance impact)
+    persistence_enabled: bool = True  # Persist blockchain to disk
+
+
+@dataclass
+class FeatureFlags:
+    """Feature flags."""
+    # Experimental features
+    enable_temporal_queries: bool = True  # Enable time-travel queries
+    enable_distributed_mode: bool = False
+    enable_replication: bool = False
+    
+    # Advanced features
+    enable_full_text_search: bool = True
+    enable_vector_search: bool = True
+    enable_graph_algorithms: bool = True
+    
+    # Performance features
+    enable_query_optimizer: bool = True
+    enable_index_hints: bool = True
+
+
+@dataclass
+class DatabaseConfig:
+    """Complete database configuration."""
+    # Database identity
+    database_name: str = "contextsynapse"
+    database_version: str = "1.0.0"
+    
+    # Configuration sections
+    performance: PerformanceConfig = None
+    storage: StorageConfig = None
+    connection: ConnectionConfig = None
+    logging: LoggingConfig = None
+    security: SecurityConfig = None
+    features: FeatureFlags = None
+    traceability: TraceabilityConfig = None
+    
+    def __post_init__(self):
+        if self.performance is None:
+            self.performance = PerformanceConfig()
+        if self.storage is None:
+            self.storage = StorageConfig()
+        if self.connection is None:
+            self.connection = ConnectionConfig()
+        if self.logging is None:
+            self.logging = LoggingConfig()
+        if self.security is None:
+            self.security = SecurityConfig()
+        if self.features is None:
+            self.features = FeatureFlags()
+        if self.traceability is None:
+            self.traceability = TraceabilityConfig()
+
+
+class DatabaseConfigManager:
+    """Manages database configuration files."""
+    
+    DEFAULT_CONFIG_FILE = "contextsynapse.conf"
+    DEFAULT_CONFIG_DIR = Path("contextcore_data/config")
+    
+    def __init__(self, config_file: Optional[Union[str, Path]] = None):
+        """
+        Initialize configuration manager.
+        
+        Args:
+            config_file: Path to configuration file (default: config/core/database.yaml or contextsynapse.conf)
+        """
+        if config_file is None:
+            # Try multiple locations (new structure first, then legacy fallbacks)
+            possible_locations = [
+                Path("config/core/database.yaml"),  # New structure (primary)
+                Path.home() / ".contextcore" / "contextsynapse.conf",  # User home (legacy)
+                self.DEFAULT_CONFIG_DIR / "contextsynapse.conf",  # Data directory (legacy)
+                Path(self.DEFAULT_CONFIG_FILE),  # Legacy: Current directory (last resort)
+            ]
+            
+            for loc in possible_locations:
+                if loc.exists():
+                    config_file = loc
+                    break
+            else:
+                # Use default location
+                config_file = Path(self.DEFAULT_CONFIG_FILE)
+        else:
+            config_file = Path(config_file)
+        
+        self.config_file = config_file
+        self.config = self._load_config()
+    
+    def _load_config(self) -> DatabaseConfig:
+        """Load configuration from file or return defaults."""
+        if not self.config_file.exists():
+            logger.info(f"Config file not found: {self.config_file}, using defaults")
+            return DatabaseConfig()
+        
+        try:
+            with open(self.config_file, 'r') as f:
+                if self.config_file.suffix in ['.yaml', '.yml']:
+                    data = yaml.safe_load(f) or {}
+                elif self.config_file.suffix == '.json':
+                    data = json.load(f)
+                else:
+                    # Try YAML first, then JSON
+                    try:
+                        f.seek(0)
+                        data = yaml.safe_load(f) or {}
+                    except:
+                        f.seek(0)
+                        data = json.load(f)
+            
+            return self._dict_to_config(data)
+            
+        except Exception as e:
+            logger.error(f"Failed to load config from {self.config_file}: {e}")
+            logger.info("Using default configuration")
+            return DatabaseConfig()
+    
+    def _dict_to_config(self, data: Dict[str, Any]) -> DatabaseConfig:
+        """Convert dictionary to DatabaseConfig."""
+        config = DatabaseConfig()
+        
+        # Database identity
+        config.database_name = data.get('database_name', config.database_name)
+        config.database_version = data.get('database_version', config.database_version)
+        
+        # Performance
+        if 'performance' in data:
+            perf_data = data['performance']
+            config.performance = PerformanceConfig(**{
+                k: v for k, v in perf_data.items() 
+                if k in PerformanceConfig.__annotations__
+            })
+        
+        # Storage
+        if 'storage' in data:
+            storage_data = data['storage']
+            config.storage = StorageConfig(**{
+                k: v for k, v in storage_data.items()
+                if k in StorageConfig.__annotations__
+            })
+        
+        # Connection
+        if 'connection' in data:
+            conn_data = data['connection']
+            config.connection = ConnectionConfig(**{
+                k: v for k, v in conn_data.items()
+                if k in ConnectionConfig.__annotations__
+            })
+        
+        # Logging
+        if 'logging' in data:
+            log_data = data['logging']
+            config.logging = LoggingConfig(**{
+                k: v for k, v in log_data.items()
+                if k in LoggingConfig.__annotations__
+            })
+        
+        # Security
+        if 'security' in data:
+            sec_data = data['security']
+            config.security = SecurityConfig(**{
+                k: v for k, v in sec_data.items()
+                if k in SecurityConfig.__annotations__
+            })
+        
+        # Features
+        if 'features' in data:
+            feat_data = data['features']
+            config.features = FeatureFlags(**{
+                k: v for k, v in feat_data.items()
+                if k in FeatureFlags.__annotations__
+            })
+        
+        # Traceability (Blockchain)
+        if 'traceability' in data:
+            trace_data = data['traceability']
+            config.traceability = TraceabilityConfig(**{
+                k: v for k, v in trace_data.items()
+                if k in TraceabilityConfig.__annotations__
+            })
+        
+        return config
+    
+    def save_config(self, config: Optional[DatabaseConfig] = None, format: ConfigFormat = ConfigFormat.YAML):
+        """Save configuration to file."""
+        if config is None:
+            config = self.config
+        
+        self.config_file.parent.mkdir(parents=True, exist_ok=True)
+        
+        try:
+            config_dict = self._config_to_dict(config)
+            
+            with open(self.config_file, 'w') as f:
+                if format == ConfigFormat.YAML:
+                    yaml.dump(config_dict, f, default_flow_style=False, sort_keys=False)
+                elif format == ConfigFormat.JSON:
+                    json.dump(config_dict, f, indent=2, sort_keys=False)
+            
+            logger.info(f"Configuration saved to {self.config_file}")
+            
+        except Exception as e:
+            logger.error(f"Failed to save config to {self.config_file}: {e}")
+            raise
+    
+    def _config_to_dict(self, config: DatabaseConfig) -> Dict[str, Any]:
+        """Convert DatabaseConfig to dictionary."""
+        return {
+            'database_name': config.database_name,
+            'database_version': config.database_version,
+            'performance': asdict(config.performance),
+            'storage': asdict(config.storage),
+            'connection': asdict(config.connection),
+            'logging': asdict(config.logging),
+            'security': asdict(config.security),
+            'features': asdict(config.features),
+            'traceability': asdict(config.traceability),
+        }
+    
+    def get_config(self) -> DatabaseConfig:
+        """Get current configuration."""
+        return self.config
+    
+    def update_config(self, section: str, **kwargs):
+        """Update configuration section."""
+        if not hasattr(self.config, section):
+            raise ValueError(f"Unknown config section: {section}")
+        
+        section_obj = getattr(self.config, section)
+        for key, value in kwargs.items():
+            if hasattr(section_obj, key):
+                setattr(section_obj, key, value)
+            else:
+                logger.warning(f"Unknown config key: {section}.{key}")
+    
+    def create_default_config(self, output_file: Optional[Union[str, Path]] = None):
+        """Create a default configuration file with all options."""
+        if output_file is None:
+            output_file = self.config_file
+        
+        output_file = Path(output_file)
+        output_file.parent.mkdir(parents=True, exist_ok=True)
+        
+        default_config = DatabaseConfig()
+        self.save_config(default_config, format=ConfigFormat.YAML)
+        
+        logger.info(f"Default configuration created at {output_file}")
+
+
+# Global config manager instance
+_global_config_manager: Optional[DatabaseConfigManager] = None
+
+
+def get_config_manager(config_file: Optional[Union[str, Path]] = None) -> DatabaseConfigManager:
+    """Get or create global configuration manager."""
+    global _global_config_manager
+    if _global_config_manager is None:
+        _global_config_manager = DatabaseConfigManager(config_file)
+    return _global_config_manager
+
+
+def get_config() -> DatabaseConfig:
+    """Get current database configuration."""
+    return get_config_manager().get_config()
+
+
+

contextsynapse/config/deployment.py

@@ -0,0 +1,221 @@
+"""
+Deployment Configuration — single settings file for local, Docker, and K8s.
+
+All deployment-specific behavior is controlled here. Switch between local dev,
+Docker Compose, and Kubernetes by changing CONTEXTSYNAPSE_DEPLOY_MODE env var
+or editing deploy_settings.yaml.
+
+Usage:
+    from contextsynapse.config.deployment import get_deploy_config
+
+    config = get_deploy_config()
+    storage_backend = config.storage_backend  # "local", "s3", "gcs"
+    redis_url = config.redis_url
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+# Deployment modes
+MODE_LOCAL = "local"         # Local dev — file storage, optional Redis
+MODE_DOCKER = "docker"       # Docker Compose — Redis + local volumes
+MODE_K8S = "kubernetes"      # Kubernetes — Redis + shared/cloud storage
+
+
+@dataclass
+class DeployConfig:
+    """Deployment configuration — all infra settings in one place."""
+
+    # Core
+    mode: str = MODE_LOCAL
+    api_host: str = "0.0.0.0"
+    api_port: int = 8000
+    workers: int = 1
+    log_level: str = "info"
+
+    # Redis
+    redis_url: str = ""
+    redis_enabled: bool = False
+
+    # Storage backend: "local", "s3", "gcs", "azure"
+    storage_backend: str = "local"
+    storage_path: str = "contextcore_data"  # local path or bucket prefix
+
+    # S3 settings (when storage_backend = "s3")
+    s3_bucket: str = ""
+    s3_region: str = "us-east-1"
+    s3_prefix: str = "graphs/"
+    s3_endpoint: str = ""  # for MinIO or R2
+
+    # GCS settings (when storage_backend = "gcs")
+    gcs_bucket: str = ""
+    gcs_prefix: str = "graphs/"
+
+    # Azure Blob settings (when storage_backend = "azure")
+    azure_container: str = ""
+    azure_connection_string: str = ""
+
+    # Graph backend: "redis" (shared, default) or "csr" (in-memory, dev only)
+    graph_backend: str = "redis"
+
+    # Vector DB
+    vector_backend: str = "custom"  # "custom", "qdrant", "chromadb"
+    qdrant_url: str = ""
+
+    # Embedding
+    embedding_provider: str = "ollama"  # "ollama", "openai", "cohere"
+    embedding_model: str = "nomic-embed-text"
+    embedding_url: str = "http://localhost:11434"
+
+    # LLM
+    llm_provider: str = "groq"
+    llm_model: str = "gpt-oss-120b"
+    llm_max_concurrent: int = 10
+    llm_rpm: int = 100
+
+    # Ingestion workers
+    ingestion_workers: int = 2
+    ingestion_queue_max: int = 100
+
+    # Quotas (SaaS)
+    default_graphs_per_tenant: int = 50
+    default_nodes_per_tenant: int = 100000
+    default_storage_mb_per_tenant: int = 500
+
+    # K8s specific
+    k8s_namespace: str = "contextsynapse"
+    k8s_service_account: str = "contextcore-sa"
+    pod_memory_limit: str = "2Gi"
+    pod_cpu_limit: str = "1"
+
+    # Write-behind
+    write_behind_interval: int = 10
+    max_graphs_in_memory: int = 50
+
+    def to_env(self) -> Dict[str, str]:
+        """Export config as environment variables (uses new CONTEXTSYNAPSE_ prefix)."""
+        env = {}
+        if self.redis_url:
+            env["CONTEXTSYNAPSE_REDIS_URL"] = self.redis_url
+        env["CONTEXTSYNAPSE_GRAPH_BACKEND"] = self.graph_backend
+        if self.qdrant_url:
+            env["QDRANT_URL"] = self.qdrant_url
+        env["CONTEXTSYNAPSE_DEPLOY_MODE"] = self.mode
+        env["CONTEXTSYNAPSE_STORAGE_BACKEND"] = self.storage_backend
+        env["CONTEXTSYNAPSE_STORAGE_PATH"] = self.storage_path
+        env["CONTEXTSYNAPSE_LLM_MAX_CONCURRENT"] = str(self.llm_max_concurrent)
+        env["CONTEXTSYNAPSE_LLM_RPM"] = str(self.llm_rpm)
+        env["CONTEXTSYNAPSE_MAX_GRAPHS"] = str(self.max_graphs_in_memory)
+        env["CONTEXTSYNAPSE_WB_FLUSH_INTERVAL"] = str(self.write_behind_interval)
+        if self.s3_bucket:
+            env["CONTEXTSYNAPSE_S3_BUCKET"] = self.s3_bucket
+            env["CONTEXTSYNAPSE_S3_REGION"] = self.s3_region
+            env["CONTEXTSYNAPSE_S3_PREFIX"] = self.s3_prefix
+        if self.gcs_bucket:
+            env["CONTEXTSYNAPSE_GCS_BUCKET"] = self.gcs_bucket
+        return env
+
+
+def _load_from_yaml() -> Optional[Dict[str, Any]]:
+    """Try to load deploy_settings.yaml from project root."""
+    paths = [
+        Path("deploy_settings.yaml"),
+        Path("config/deploy_settings.yaml"),
+        Path("/etc/contextcore/deploy_settings.yaml"),
+    ]
+    for p in paths:
+        if p.exists():
+            try:
+                import yaml
+                with open(p) as f:
+                    data = yaml.safe_load(f)
+                logger.info("Loaded deploy config from %s", p)
+                return data
+            except Exception as e:
+                logger.warning("Failed to load %s: %s", p, e)
+    return None
+
+
+def _load_from_env() -> Dict[str, Any]:
+    """Load config from environment variables."""
+    config = {}
+    # Each entry: (new_CONTEXTSYNAPSE_key, old_AICONTEXTDB_key, config_key)
+    mapping = [
+        ("CONTEXTSYNAPSE_DEPLOY_MODE", "AICONTEXTDB_DEPLOY_MODE", "mode"),
+        ("CONTEXTSYNAPSE_REDIS_URL", "AICONTEXTDB_REDIS_URL", "redis_url"),
+        ("CONTEXTSYNAPSE_STORAGE_BACKEND", "AICONTEXTDB_STORAGE_BACKEND", "storage_backend"),
+        ("CONTEXTSYNAPSE_STORAGE_PATH", "AICONTEXTDB_STORAGE_PATH", "storage_path"),
+        ("CONTEXTSYNAPSE_S3_BUCKET", "AICONTEXTDB_S3_BUCKET", "s3_bucket"),
+        ("CONTEXTSYNAPSE_S3_REGION", "AICONTEXTDB_S3_REGION", "s3_region"),
+        ("CONTEXTSYNAPSE_S3_PREFIX", "AICONTEXTDB_S3_PREFIX", "s3_prefix"),
+        ("CONTEXTSYNAPSE_S3_ENDPOINT", "AICONTEXTDB_S3_ENDPOINT", "s3_endpoint"),
+        ("CONTEXTSYNAPSE_GCS_BUCKET", "AICONTEXTDB_GCS_BUCKET", "gcs_bucket"),
+        ("CONTEXTSYNAPSE_GCS_PREFIX", "AICONTEXTDB_GCS_PREFIX", "gcs_prefix"),
+        (None, "QDRANT_URL", "qdrant_url"),
+        ("CONTEXTSYNAPSE_GRAPH_BACKEND", "AICONTEXTDB_GRAPH_BACKEND", "graph_backend"),
+        ("CONTEXTSYNAPSE_LLM_MAX_CONCURRENT", "AICONTEXTDB_LLM_MAX_CONCURRENT", "llm_max_concurrent"),
+        ("CONTEXTSYNAPSE_LLM_RPM", "AICONTEXTDB_LLM_RPM", "llm_rpm"),
+        ("CONTEXTSYNAPSE_MAX_GRAPHS", "AICONTEXTDB_MAX_GRAPHS", "max_graphs_in_memory"),
+        ("CONTEXTSYNAPSE_WB_FLUSH_INTERVAL", "AICONTEXTDB_WB_FLUSH_INTERVAL", "write_behind_interval"),
+        (None, "API_PORT", "api_port"),
+        ("CONTEXTSYNAPSE_LOG_LEVEL", "AICONTEXTDB_LOG_LEVEL", "log_level"),
+    ]
+    for new_env_key, old_env_key, config_key in mapping:
+        val = (os.environ.get(new_env_key) if new_env_key else None) or os.environ.get(old_env_key)
+        if val is not None:
+            # Convert numeric fields
+            if config_key in ("api_port", "workers", "llm_max_concurrent", "llm_rpm",
+                              "max_graphs_in_memory", "write_behind_interval", "ingestion_workers"):
+                try:
+                    val = int(val)
+                except ValueError:
+                    pass
+            config[config_key] = val
+    return config
+
+
+# Singleton
+_config: Optional[DeployConfig] = None
+
+
+def get_deploy_config() -> DeployConfig:
+    """Get deployment config — YAML file → env vars → defaults."""
+    global _config
+    if _config is not None:
+        return _config
+
+    config = DeployConfig()
+
+    # Layer 1: YAML file
+    yaml_data = _load_from_yaml()
+    if yaml_data:
+        for key, val in yaml_data.items():
+            if hasattr(config, key):
+                setattr(config, key, val)
+
+    # Layer 2: Environment variables (override YAML)
+    env_data = _load_from_env()
+    for key, val in env_data.items():
+        if hasattr(config, key):
+            setattr(config, key, val)
+
+    # Auto-detect mode
+    if not config.mode or config.mode == MODE_LOCAL:
+        if os.environ.get("KUBERNETES_SERVICE_HOST"):
+            config.mode = MODE_K8S
+        elif os.path.exists("/.dockerenv"):
+            config.mode = MODE_DOCKER
+
+    # Auto-enable Redis
+    config.redis_enabled = bool(config.redis_url)
+
+    logger.info("[DEPLOY] Mode=%s, storage=%s, redis=%s", config.mode, config.storage_backend, config.redis_enabled)
+    _config = config
+    return _config