Configuring Code-Graph-RAG Using Settings and Environment Variables

Code‑Graph‑RAG reads all runtime configuration from environment variables (or a .env file) parsed through the AppConfig class in codebase_rag/config.py.

This open-source repository by vitali87/code-graph-rag uses pydantic-settings to centralize every tunable parameter—from graph database connection details to API keys and security policies—making system behavior predictable and version-controllable.

How Configuration Loading Works

The configuration flow follows a strict three-stage pipeline implemented in codebase_rag/config.py:

1. Dotenv loading – load_dotenv() executes at import time (line 20), pulling variables from .env into os.environ.
2. Pydantic validation – AppConfig(BaseSettings) instantiates once as settings = AppConfig() (lines 46–47), reading from environment variables with case-insensitive matching.
3. System-wide access – Any module imports settings from codebase_rag.config and accesses typed attributes directly.

The SettingsConfigDict (lines 52–56) explicitly configures:

SettingsConfigDict(
    env_file=".env",
    env_file_encoding="utf-8",
    case_sensitive=False
)

Core Configuration Variables

All settings are declared as fields on AppConfig with sensible defaults. When a variable is omitted, the system uses the hard-coded default from the field definition.

Database Connection

Variable	Default	Purpose
MEMGRAPH_HOST	localhost	Hostname for the Memgraph graph database
MEMGRAPH_PORT	7687	Bolt protocol port
MEMGRAPH_USER	(none)	Authentication username
MEMGRAPH_PASSWORD	(none)	Authentication password

LLM Orchestrator Settings

The ORCHESTRATOR_PROVIDER and ORCHESTRATOR_MODEL fields control which LLM handles query planning and response generation. Supported providers are defined in constants.Provider.

Vector Store Backend

VECTOR_STORE_BACKEND accepts enum values from cs.VectorStoreBackend (lines 79–81), selecting between implementations like memgraph, qdrant, or chroma.

Provider-Specific API Key Validation

Remote providers require authenticated access. The ModelConfig.validate_api_key() method (lines 21–44) enforces this through the API_KEY_INFO mapping:

API_KEY_INFO = {
    cs.Provider.OPENAI: "OPENAI_API_KEY",
    cs.Provider.ANTHROPIC: "ANTHROPIC_API_KEY",
    cs.Provider.GOOGLE: "GOOGLE_API_KEY",
    # ...

}

If ORCHESTRATOR_PROVIDER=openai is set but OPENAI_API_KEY is missing, the system raises a clear validation error before any network call occurs.

Complete Configuration Examples

Local Ollama Setup (No API Keys Required)

# .env

MEMGRAPH_HOST=localhost
MEMGRAPH_PORT=7687
OLLAMA_BASE_URL=http://localhost:11434
ORCHESTRATOR_PROVIDER=ollama
ORCHESTRATOR_MODEL=llama3.1

Ollama is recognized as a local provider (LOCAL_PROVIDERS = {cs.Provider.OLLAMA}, lines 99–100), bypassing API key checks entirely.

OpenAI Cloud Setup

# .env

ORCHESTRATOR_PROVIDER=openai
ORCHESTRATOR_MODEL=gpt-4o
OPENAI_API_KEY=sk-XXXXXXXXXXXXXXXXXXXXXXXX

Qdrant Vector Store Configuration

# .env

VECTOR_STORE_BACKEND=qdrant
QDRANT_URL=http://localhost:6333
QDRANT_COLLECTION_NAME=code_embeddings

Security: Shell Command Restrictions

# .env

SHELL_COMMAND_ALLOWLIST=ls,rg,git,python
SHELL_READ_ONLY_COMMANDS=ls,cat,grep

Both fields parse as frozensets via pydantic. The allowlist restricts which commands the internal sandbox permits; SHELL_READ_ONLY_COMMANDS further constrains operations that cannot modify filesystem state.

Accessing Settings in Python Code

from codebase_rag.config import settings

# Typed attributes with full IDE support

print("Graph host:", settings.MEMGRAPH_HOST)
print("Orchestrator model:", settings.ORCHESTRATOR_MODEL)
print("Embedding backend:", settings.VECTOR_STORE_BACKEND.value)

# Check if running against local LLM

if settings.ORCHESTRATOR_PROVIDER in settings.LOCAL_PROVIDERS:
    print("Using local provider—no API key needed")

Key Source Files

All configuration logic is centralized in these locations:

• codebase_rag/config.py – AppConfig definition, load_dotenv() call, API_KEY_INFO mapping, and all environment variable declarations.
• .env.example – Exhaustive reference of every supported variable with placeholder values.
• codebase_rag/models.py – ModelConfig dataclass containing provider-specific validation logic.
• codebase_rag/constants.py – Enum definitions for Provider, VectorStoreBackend, and other typed configuration values.

Extending the Configuration System

To add a new environment variable:

1. Add a typed field to AppConfig with an appropriate default (or None for required values).
2. If provider-specific, add the key mapping to API_KEY_INFO.
3. Update .env.example with documentation.

This pattern keeps the configuration self-documenting and ensures consistent error messaging across the codebase.

Summary

• All settings in vitali87/code-graph-rAG derive from environment variables loaded via python-dotenv and validated through pydantic-settings.
• codebase_rag/config.py instantiates a singleton settings object that modules import directly.
• Provider API keys are enforced automatically through ModelConfig.validate_api_key() and the API_KEY_INFO registry.
• Local providers (Ollama) require no authentication; remote providers fail fast with clear error messages if keys are missing.
• Security policies like shell command restrictions are configurable through frozenset-parsed environment variables.

Frequently Asked Questions

What happens if I don't create a .env file?

The system falls back to hard-coded defaults defined in AppConfig fields. For local development with Memgraph and Ollama on standard ports, no .env file is required—localhost defaults apply.

How do I switch from Ollama to OpenAI without code changes?

Set ORCHESTRATOR_PROVIDER=openai and OPENAI_API_KEY=sk-... in your .env file, then restart the application. The AppConfig model re-reads environment variables on every import.

Can I use multiple vector store backends simultaneously?

No—the VECTOR_STORE_BACKEND field accepts a single VectorStoreBackend enum value. The system instantiates one backend at startup based on this selection.

Where should I add a new environment variable for a custom feature?

Add it to AppConfig in codebase_rag/config.py with a type annotation and default value. If it controls model behavior, consider adding validation logic in codebase_rag/models.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}