code-explore 0.1.0__tar.gz → 0.2.0__tar.gz

{code_explore-0.1.0 → code_explore-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-explore
-Version: 0.1.0
+Version: 0.2.0
 Summary: Developer knowledge base CLI — scan, index, and search your programming projects
 Project-URL: Homepage, https://github.com/aipioneers/code-explore
 Project-URL: Repository, https://github.com/aipioneers/code-explore
@@ -24,7 +24,9 @@ Requires-Dist: httpx>=0.24.0
 Requires-Dist: lancedb>=0.4.0
 Requires-Dist: pyarrow>=14.0.0
 Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0.0
 Requires-Dist: rich>=13.0.0
+Requires-Dist: tomli-w>=1.0.0
 Requires-Dist: typer>=0.9.0
 Provides-Extra: api
 Requires-Dist: fastapi>=0.100.0; extra == 'api'

code_explore-0.2.0/code_explore/cli/config_cmd.py

@@ -0,0 +1,96 @@
+"""CLI commands for configuration management."""
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from code_explore.config import (
+    _get_config_dir,
+    get_config_path,
+    get_resolved_settings,
+    reset_config,
+    write_default_config,
+    _discover_config_file,
+)
+
+config_app = typer.Typer(
+    name="config",
+    help="Manage code-explore configuration.",
+    no_args_is_help=True,
+)
+console = Console()
+
+
+@config_app.command()
+def show() -> None:
+    """Display all current settings with values and sources."""
+    settings = get_resolved_settings()
+    config_path = get_config_path()
+
+    table = Table(title="Code Explore Configuration")
+    table.add_column("Setting", style="cyan", no_wrap=True)
+    table.add_column("Value", style="white")
+    table.add_column("Source", style="green")
+
+    for s in settings:
+        table.add_row(s.name, s.value, s.source.value)
+
+    table.add_section()
+    path_display = str(config_path) if config_path else "(no config file)"
+    table.add_row("Config file", path_display, "")
+
+    console.print(table)
+
+
+@config_app.command()
+def init(
+    fmt: str = typer.Option("toml", "--format", "-f", help="Config format: toml or yaml"),
+    force: bool = typer.Option(False, "--force", help="Overwrite existing config file"),
+) -> None:
+    """Create a configuration file with all default values."""
+    config_dir = _get_config_dir()
+    ext = "yaml" if fmt in ("yaml", "yml") else "toml"
+    path = config_dir / f"config.{ext}"
+
+    if path.exists() and not force:
+        console.print(
+            f"[yellow]Config file already exists:[/yellow] {path}\n"
+            f"Use [bold]--force[/bold] to overwrite."
+        )
+        raise typer.Exit(1)
+
+    write_default_config(path, fmt=ext)
+    console.print(f"[green]Created configuration file:[/green] {path}")
+
+
+@config_app.command()
+def reset(
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
+) -> None:
+    """Delete the configuration file and revert to defaults."""
+    config_path = _discover_config_file()
+
+    if not config_path:
+        console.print("[yellow]No configuration file found. Already using defaults.[/yellow]")
+        raise typer.Exit(0)
+
+    if not yes:
+        confirm = typer.confirm(f"Delete {config_path} and revert to defaults?")
+        if not confirm:
+            console.print("[dim]Cancelled.[/dim]")
+            raise typer.Exit(0)
+
+    config_path.unlink()
+    reset_config()
+    console.print(f"[green]Reset configuration to defaults.[/green] Removed: {config_path}")
+
+
+@config_app.command()
+def path() -> None:
+    """Print the path to the active configuration file."""
+    config_path = _discover_config_file()
+    if config_path:
+        console.print(str(config_path))
+    else:
+        default_path = _get_config_dir() / "config.toml"
+        console.print(f"{default_path} [dim](not created yet)[/dim]")

{code_explore-0.1.0 → code_explore-0.2.0}/code_explore/cli/main.py

@@ -14,12 +14,14 @@ from rich.tree import Tree
 
 from code_explore.database import init_db, save_project, get_project, get_all_projects, get_project_count
 from code_explore.models import Project, ProjectSource, ProjectStatus
+from code_explore.cli.config_cmd import config_app
 
 app = typer.Typer(
     name="code-explore",
     help="Personal developer knowledge base - index, analyze and search all your projects.",
     no_args_is_help=True,
 )
+app.add_typer(config_app, name="config")
 console = Console()
 
 
@@ -142,9 +144,13 @@ def scan(
 def search(
     query: str = typer.Argument(..., help="Search query"),
     mode: str = typer.Option("hybrid", "--mode", "-m", help="Search mode: fulltext, semantic, or hybrid"),
-    limit: int = typer.Option(20, "--limit", "-l", help="Maximum results"),
+    limit: int = typer.Option(None, "--limit", "-l", help="Maximum results"),
 ) -> None:
     """Search across all indexed projects."""
+    from code_explore.config import get_config
+
+    if limit is None:
+        limit = get_config().result_limit
     init_db()
 
     if mode == "fulltext":

code_explore-0.2.0/code_explore/config.py

@@ -0,0 +1,329 @@
+"""Configuration management for Code Explore.
+
+Loads settings from: built-in defaults → config file → environment variables.
+Config file supports TOML and YAML formats, auto-detected by file extension.
+"""
+
+import logging
+import os
+import tomllib
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+logger = logging.getLogger(__name__)
+
+
+class ConfigSource(str, Enum):
+    """Where a configuration value came from."""
+
+    DEFAULT = "default"
+    FILE = "file"
+    ENV = "env"
+    CLI = "cli"
+
+
+class ResolvedSetting(BaseModel):
+    """A single setting with its resolved value and source."""
+
+    name: str
+    key: str
+    value: str
+    source: ConfigSource
+
+
+class AppConfig(BaseModel):
+    """Application configuration with all settings and their defaults."""
+
+    ollama_url: str = Field(default="http://localhost:11434")
+    summary_model: str = Field(default="llama3.2:3b")
+    embedding_model: str = Field(default="qwen3-embedding:8b")
+    embedding_dim: int = Field(default=4096)
+    db_path: Path = Field(default_factory=lambda: Path.home() / ".code-explore" / "code-explore.db")
+    vector_path: Path = Field(default_factory=lambda: Path.home() / ".code-explore" / "vectors")
+    rrf_k: int = Field(default=60)
+    result_limit: int = Field(default=20)
+
+
+# Mapping: env var name → (config file section.key, AppConfig field name)
+_ENV_MAP: dict[str, tuple[str, str]] = {
+    "CEX_OLLAMA_URL": ("ollama.url", "ollama_url"),
+    "CEX_OLLAMA_SUMMARY_MODEL": ("ollama.summary_model", "summary_model"),
+    "CEX_OLLAMA_EMBEDDING_MODEL": ("ollama.embedding_model", "embedding_model"),
+    "CEX_OLLAMA_EMBEDDING_DIM": ("ollama.embedding_dim", "embedding_dim"),
+    "CEX_STORAGE_DB_PATH": ("storage.db_path", "db_path"),
+    "CEX_STORAGE_VECTOR_PATH": ("storage.vector_path", "vector_path"),
+    "CEX_SEARCH_RRF_K": ("search.rrf_k", "rrf_k"),
+    "CEX_SEARCH_RESULT_LIMIT": ("search.result_limit", "result_limit"),
+}
+
+# Mapping: AppConfig field name → (config file section, key within section)
+_FIELD_TO_FILE_KEY: dict[str, tuple[str, str]] = {
+    "ollama_url": ("ollama", "url"),
+    "summary_model": ("ollama", "summary_model"),
+    "embedding_model": ("ollama", "embedding_model"),
+    "embedding_dim": ("ollama", "embedding_dim"),
+    "db_path": ("storage", "db_path"),
+    "vector_path": ("storage", "vector_path"),
+    "rrf_k": ("search", "rrf_k"),
+    "result_limit": ("search", "result_limit"),
+}
+
+# Human-readable display names
+_FIELD_DISPLAY_NAMES: dict[str, str] = {
+    "ollama_url": "Ollama URL",
+    "summary_model": "Summary model",
+    "embedding_model": "Embedding model",
+    "embedding_dim": "Embedding dimension",
+    "db_path": "Database path",
+    "vector_path": "Vector store path",
+    "rrf_k": "Search fusion (k)",
+    "result_limit": "Result limit",
+}
+
+
+def _get_config_dir() -> Path:
+    """Return the configuration directory, respecting XDG_CONFIG_HOME."""
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    if xdg:
+        return Path(xdg) / "code-explore"
+    return Path.home() / ".config" / "code-explore"
+
+
+def _discover_config_file(config_dir: Path | None = None) -> Path | None:
+    """Search for config file in priority order: .toml → .yaml → .yml."""
+    d = config_dir or _get_config_dir()
+    candidates = [d / "config.toml", d / "config.yaml", d / "config.yml"]
+    found: list[Path] = [p for p in candidates if p.is_file()]
+
+    if not found:
+        return None
+
+    if len(found) > 1:
+        logger.warning(
+            "Multiple config files found. Using %s, ignoring: %s",
+            found[0],
+            ", ".join(str(p) for p in found[1:]),
+        )
+
+    return found[0]
+
+
+def _load_file(path: Path) -> dict[str, Any]:
+    """Load a config file (TOML or YAML) and return a flat field dict."""
+    try:
+        raw = path.read_bytes()
+    except OSError as e:
+        logger.warning("Cannot read config file %s: %s", path, e)
+        return {}
+
+    suffix = path.suffix.lower()
+    nested: dict[str, Any] = {}
+
+    if suffix == ".toml":
+        try:
+            nested = tomllib.loads(raw.decode("utf-8"))
+        except (tomllib.TOMLDecodeError, UnicodeDecodeError) as e:
+            logger.warning("Failed to parse TOML config %s: %s. Using defaults.", path, e)
+            return {}
+    elif suffix in (".yaml", ".yml"):
+        try:
+            import yaml
+
+            nested = yaml.safe_load(raw.decode("utf-8")) or {}
+        except Exception as e:
+            logger.warning("Failed to parse YAML config %s: %s. Using defaults.", path, e)
+            return {}
+    else:
+        logger.warning("Unsupported config file format: %s. Expected .toml, .yaml, or .yml.", path)
+        return {}
+
+    # Flatten nested dict to field names
+    flat: dict[str, Any] = {}
+    for field_name, (section, key) in _FIELD_TO_FILE_KEY.items():
+        if section in nested and isinstance(nested[section], dict):
+            if key in nested[section]:
+                flat[field_name] = nested[section][key]
+
+    return flat
+
+
+def _load_env_vars() -> dict[str, Any]:
+    """Load configuration overrides from CEX_* environment variables."""
+    result: dict[str, Any] = {}
+    int_fields = {"embedding_dim", "rrf_k", "result_limit"}
+
+    for env_var, (_file_key, field_name) in _ENV_MAP.items():
+        value = os.environ.get(env_var)
+        if value is not None:
+            if field_name in int_fields:
+                try:
+                    result[field_name] = int(value)
+                except ValueError:
+                    logger.warning(
+                        "Invalid integer value for %s=%s. Ignoring.", env_var, value
+                    )
+            else:
+                result[field_name] = value
+
+    return result
+
+
+def _resolve_config(
+    file_dict: dict[str, Any],
+    env_dict: dict[str, Any],
+) -> tuple[AppConfig, dict[str, ConfigSource]]:
+    """Layer defaults → file → env and track provenance."""
+    sources: dict[str, ConfigSource] = {
+        field: ConfigSource.DEFAULT for field in _FIELD_DISPLAY_NAMES
+    }
+
+    merged: dict[str, Any] = {}
+
+    # Layer file values
+    for key, value in file_dict.items():
+        merged[key] = value
+        sources[key] = ConfigSource.FILE
+
+    # Layer env values (override file)
+    for key, value in env_dict.items():
+        merged[key] = value
+        sources[key] = ConfigSource.ENV
+
+    config = AppConfig(**merged) if merged else AppConfig()
+    return config, sources
+
+
+def _validate_config(config: AppConfig) -> None:
+    """Validate configuration values. Raises ValueError on invalid settings."""
+    errors: list[str] = []
+
+    if config.embedding_dim <= 0:
+        errors.append("Embedding dimension must be a positive integer.")
+    if config.rrf_k <= 0:
+        errors.append("Search fusion constant must be a positive integer.")
+    if not 1 <= config.result_limit <= 1000:
+        errors.append("Result limit must be between 1 and 1000.")
+    if not config.ollama_url.startswith(("http://", "https://")):
+        errors.append(f"Ollama URL must start with http:// or https://, got: {config.ollama_url}")
+
+    if errors:
+        raise ValueError("Configuration errors:\n" + "\n".join(f"  - {e}" for e in errors))
+
+
+def write_default_config(path: Path, fmt: str = "toml") -> None:
+    """Write a config file with all default values."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    defaults = AppConfig()
+
+    if fmt == "toml":
+        import tomli_w
+
+        data = {
+            "ollama": {
+                "url": defaults.ollama_url,
+                "summary_model": defaults.summary_model,
+                "embedding_model": defaults.embedding_model,
+                "embedding_dim": defaults.embedding_dim,
+            },
+            "storage": {
+                "db_path": str(defaults.db_path),
+                "vector_path": str(defaults.vector_path),
+            },
+            "search": {
+                "rrf_k": defaults.rrf_k,
+                "result_limit": defaults.result_limit,
+            },
+        }
+        path.write_bytes(tomli_w.dumps(data).encode("utf-8"))
+    elif fmt in ("yaml", "yml"):
+        import yaml
+
+        data = {
+            "ollama": {
+                "url": defaults.ollama_url,
+                "summary_model": defaults.summary_model,
+                "embedding_model": defaults.embedding_model,
+                "embedding_dim": defaults.embedding_dim,
+            },
+            "storage": {
+                "db_path": str(defaults.db_path),
+                "vector_path": str(defaults.vector_path),
+            },
+            "search": {
+                "rrf_k": defaults.rrf_k,
+                "result_limit": defaults.result_limit,
+            },
+        }
+        path.write_text(yaml.dump(data, default_flow_style=False, sort_keys=False))
+
+
+# --- Singleton ---
+
+_cached_config: AppConfig | None = None
+_cached_sources: dict[str, ConfigSource] | None = None
+_cached_config_path: Path | None = None
+
+
+def reset_config() -> None:
+    """Clear the cached configuration. Used for testing and after config reset."""
+    global _cached_config, _cached_sources, _cached_config_path
+    _cached_config = None
+    _cached_sources = None
+    _cached_config_path = None
+
+
+def get_config() -> AppConfig:
+    """Load and return the application configuration (cached after first call)."""
+    global _cached_config, _cached_sources, _cached_config_path
+
+    if _cached_config is not None:
+        return _cached_config
+
+    file_dict: dict[str, Any] = {}
+    config_path = _discover_config_file()
+    _cached_config_path = config_path
+
+    if config_path:
+        file_dict = _load_file(config_path)
+
+    env_dict = _load_env_vars()
+    config, sources = _resolve_config(file_dict, env_dict)
+
+    try:
+        _validate_config(config)
+    except ValueError as e:
+        logger.warning("%s", e)
+
+    _cached_config = config
+    _cached_sources = sources
+    return config
+
+
+def get_resolved_settings() -> list[ResolvedSetting]:
+    """Return all settings with their values and sources for display."""
+    config = get_config()
+    sources = _cached_sources or {f: ConfigSource.DEFAULT for f in _FIELD_DISPLAY_NAMES}
+
+    settings = []
+    for field_name, display_name in _FIELD_DISPLAY_NAMES.items():
+        value = getattr(config, field_name)
+        section, key = _FIELD_TO_FILE_KEY[field_name]
+        settings.append(
+            ResolvedSetting(
+                name=display_name,
+                key=f"{section}.{key}",
+                value=str(value),
+                source=sources.get(field_name, ConfigSource.DEFAULT),
+            )
+        )
+
+    return settings
+
+
+def get_config_path() -> Path | None:
+    """Return the path to the active config file, or None."""
+    get_config()  # ensure discovery has run
+    return _cached_config_path

{code_explore-0.1.0 → code_explore-0.2.0}/code_explore/database.py

@@ -6,11 +6,11 @@ from pathlib import Path
 
 from code_explore.models import Project
 
-DEFAULT_DB_PATH = Path.home() / ".code-explore" / "code-explore.db"
-
 
 def get_db_path() -> Path:
-    path = DEFAULT_DB_PATH
+    from code_explore.config import get_config
+
+    path = get_config().db_path
     path.parent.mkdir(parents=True, exist_ok=True)
     return path
 

{code_explore-0.1.0 → code_explore-0.2.0}/code_explore/indexer/embeddings.py

@@ -11,38 +11,45 @@ from code_explore.models import Project
 
 logger = logging.getLogger(__name__)
 
-OLLAMA_BASE_URL = "http://localhost:11434"
-EMBEDDING_MODEL = "qwen3-embedding:8b"
-EMBEDDING_DIM = 4096
-VECTOR_DB_PATH = Path.home() / ".code-explore" / "vectors"
 TABLE_NAME = "project_embeddings"
 
-SCHEMA = pa.schema([
-    pa.field("id", pa.string()),
-    pa.field("text", pa.string()),
-    pa.field("vector", pa.list_(pa.float32(), EMBEDDING_DIM)),
-])
+
+def _get_schema() -> pa.Schema:
+    from code_explore.config import get_config
+
+    dim = get_config().embedding_dim
+    return pa.schema([
+        pa.field("id", pa.string()),
+        pa.field("text", pa.string()),
+        pa.field("vector", pa.list_(pa.float32(), dim)),
+    ])
 
 
 def _ollama_available() -> bool:
+    from code_explore.config import get_config
+
+    url = get_config().ollama_url
     try:
-        resp = httpx.get(f"{OLLAMA_BASE_URL}/api/tags", timeout=5.0)
+        resp = httpx.get(f"{url}/api/tags", timeout=5.0)
         return resp.status_code == 200
     except (httpx.ConnectError, httpx.TimeoutException):
         return False
 
 
 def generate_embedding(text: str) -> list[float] | None:
+    from code_explore.config import get_config
+
+    cfg = get_config()
     try:
         resp = httpx.post(
-            f"{OLLAMA_BASE_URL}/api/embeddings",
-            json={"model": EMBEDDING_MODEL, "prompt": text},
+            f"{cfg.ollama_url}/api/embeddings",
+            json={"model": cfg.embedding_model, "prompt": text},
             timeout=30.0,
         )
         resp.raise_for_status()
         return resp.json()["embedding"]
     except (httpx.ConnectError, httpx.TimeoutException):
-        logger.warning("Ollama is not running at %s. Skipping embedding generation.", OLLAMA_BASE_URL)
+        logger.warning("Ollama is not running at %s. Skipping embedding generation.", cfg.ollama_url)
         return None
     except (httpx.HTTPStatusError, KeyError) as e:
         logger.error("Failed to generate embedding: %s", e)
@@ -115,7 +122,7 @@ def _project_to_text(project: Project) -> str:
 def _get_table(db: lancedb.DBConnection) -> lancedb.table.Table:
     if TABLE_NAME in db.table_names():
         return db.open_table(TABLE_NAME)
-    return db.create_table(TABLE_NAME, schema=SCHEMA)
+    return db.create_table(TABLE_NAME, schema=_get_schema())
 
 
 def index_project(project: Project) -> None:
@@ -128,8 +135,11 @@ def index_project(project: Project) -> None:
     if vector is None:
         return
 
-    VECTOR_DB_PATH.mkdir(parents=True, exist_ok=True)
-    db = lancedb.connect(str(VECTOR_DB_PATH))
+    from code_explore.config import get_config
+
+    vector_path = get_config().vector_path
+    vector_path.mkdir(parents=True, exist_ok=True)
+    db = lancedb.connect(str(vector_path))
     table = _get_table(db)
 
     data = [{"id": project.id, "text": text, "vector": vector}]
@@ -164,8 +174,11 @@ def index_all_projects(projects: list[Project]) -> None:
         logger.warning("No embeddings generated. Skipping vector store update.")
         return
 
-    VECTOR_DB_PATH.mkdir(parents=True, exist_ok=True)
-    db = lancedb.connect(str(VECTOR_DB_PATH))
+    from code_explore.config import get_config
+
+    vector_path = get_config().vector_path
+    vector_path.mkdir(parents=True, exist_ok=True)
+    db = lancedb.connect(str(vector_path))
     table = _get_table(db)
 
     existing_ids = {item["id"] for item in data}

{code_explore-0.1.0 → code_explore-0.2.0}/code_explore/search/hybrid.py

@@ -10,20 +10,22 @@ from code_explore.search.semantic import search as semantic_search
 
 logger = logging.getLogger(__name__)
 
-RRF_K = 60
-
 
 def _reciprocal_rank_fusion(
     fulltext_results: list[SearchResult],
     semantic_results: list[SearchResult],
 ) -> list[SearchResult]:
+    from code_explore.config import get_config
+
+    rrf_k = get_config().rrf_k
+
     scores: dict[str, float] = {}
     results_map: dict[str, SearchResult] = {}
     highlights_map: dict[str, list[str]] = {}
 
     for rank, result in enumerate(fulltext_results):
         pid = result.project.id
-        scores[pid] = scores.get(pid, 0.0) + 1.0 / (RRF_K + rank + 1)
+        scores[pid] = scores.get(pid, 0.0) + 1.0 / (rrf_k + rank + 1)
         if pid not in results_map:
             results_map[pid] = result
             highlights_map[pid] = list(result.highlights)
@@ -34,7 +36,7 @@ def _reciprocal_rank_fusion(
 
     for rank, result in enumerate(semantic_results):
         pid = result.project.id
-        scores[pid] = scores.get(pid, 0.0) + 1.0 / (RRF_K + rank + 1)
+        scores[pid] = scores.get(pid, 0.0) + 1.0 / (rrf_k + rank + 1)
         if pid not in results_map:
             results_map[pid] = result
             highlights_map[pid] = list(result.highlights)

{code_explore-0.1.0 → code_explore-0.2.0}/code_explore/search/semantic.py

@@ -7,7 +7,6 @@ import lancedb
 
 from code_explore.database import get_project
 from code_explore.indexer.embeddings import (
-    VECTOR_DB_PATH,
     TABLE_NAME,
     generate_embedding,
     _ollama_available,
@@ -30,12 +29,15 @@ def search(
         logger.warning("Failed to generate query embedding. Falling back to fulltext search.")
         return fulltext_search(query, limit=limit, db_path=db_path)
 
-    if not VECTOR_DB_PATH.exists():
+    from code_explore.config import get_config
+
+    vector_path = get_config().vector_path
+    if not vector_path.exists():
         logger.warning("Vector store not found. Falling back to fulltext search.")
         return fulltext_search(query, limit=limit, db_path=db_path)
 
     try:
-        db = lancedb.connect(str(VECTOR_DB_PATH))
+        db = lancedb.connect(str(vector_path))
         if TABLE_NAME not in db.table_names():
             logger.warning("Embeddings table not found. Falling back to fulltext search.")
             return fulltext_search(query, limit=limit, db_path=db_path)

{code_explore-0.1.0 → code_explore-0.2.0}/code_explore/summarizer/ollama.py

@@ -8,9 +8,6 @@ from code_explore.models import Project
 
 logger = logging.getLogger(__name__)
 
-OLLAMA_BASE_URL = "http://localhost:11434"
-DEFAULT_MODEL = "llama3.2:3b"
-
 
 def _build_prompt(project: Project) -> str:
     parts = [f"Project: {project.name}"]
@@ -90,9 +87,16 @@ def _parse_response(text: str) -> tuple[str | None, list[str], list[str]]:
 
 def summarize_project(
     project: Project,
-    model: str = DEFAULT_MODEL,
-    base_url: str = OLLAMA_BASE_URL,
+    model: str | None = None,
+    base_url: str | None = None,
 ) -> tuple[str | None, list[str], list[str]]:
+    from code_explore.config import get_config
+
+    cfg = get_config()
+    if model is None:
+        model = cfg.summary_model
+    if base_url is None:
+        base_url = cfg.ollama_url
     prompt = _build_prompt(project)
 
     try:

{code_explore-0.1.0 → code_explore-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "code-explore"
-version = "0.1.0"
+version = "0.2.0"
 description = "Developer knowledge base CLI — scan, index, and search your programming projects"
 readme = "README.md"
 license = "MIT"
@@ -39,6 +39,8 @@ dependencies = [
     "lancedb>=0.4.0",
     "pyarrow>=14.0.0",
     "gitpython>=3.1.0",
+    "tomli_w>=1.0.0",
+    "pyyaml>=6.0.0",
 ]
 
 [project.optional-dependencies]

{code_explore-0.1.0 → code_explore-0.2.0}/tests/conftest.py

@@ -5,6 +5,7 @@ from pathlib import Path
 
 import pytest
 
+from code_explore.config import reset_config
 from code_explore.database import init_db, save_project, get_connection
 from code_explore.models import (
     DependencyInfo,
@@ -18,6 +19,14 @@ from code_explore.models import (
 )
 
 
+@pytest.fixture(autouse=True)
+def _reset_config_singleton():
+    """Reset the config singleton before each test to prevent leakage."""
+    reset_config()
+    yield
+    reset_config()
+
+
 @pytest.fixture
 def tmp_db(tmp_path):
     """Create a temporary SQLite database."""

code_explore-0.2.0/tests/test_config.py

@@ -0,0 +1,314 @@
+"""Tests for configuration module."""
+
+from pathlib import Path
+
+import pytest
+import tomllib
+
+from code_explore.config import (
+    AppConfig,
+    ConfigSource,
+    _discover_config_file,
+    _load_env_vars,
+    _load_file,
+    _resolve_config,
+    _validate_config,
+    get_config,
+    get_resolved_settings,
+    reset_config,
+    write_default_config,
+)
+
+
+class TestAppConfigDefaults:
+    """Verify all defaults match current hardcoded values."""
+
+    def test_ollama_url(self):
+        cfg = AppConfig()
+        assert cfg.ollama_url == "http://localhost:11434"
+
+    def test_summary_model(self):
+        cfg = AppConfig()
+        assert cfg.summary_model == "llama3.2:3b"
+
+    def test_embedding_model(self):
+        cfg = AppConfig()
+        assert cfg.embedding_model == "qwen3-embedding:8b"
+
+    def test_embedding_dim(self):
+        cfg = AppConfig()
+        assert cfg.embedding_dim == 4096
+
+    def test_db_path(self):
+        cfg = AppConfig()
+        assert cfg.db_path == Path.home() / ".code-explore" / "code-explore.db"
+
+    def test_vector_path(self):
+        cfg = AppConfig()
+        assert cfg.vector_path == Path.home() / ".code-explore" / "vectors"
+
+    def test_rrf_k(self):
+        cfg = AppConfig()
+        assert cfg.rrf_k == 60
+
+    def test_result_limit(self):
+        cfg = AppConfig()
+        assert cfg.result_limit == 20
+
+
+class TestLoadFile:
+    def test_toml_loading(self, tmp_path):
+        config_file = tmp_path / "config.toml"
+        config_file.write_text(
+            '[ollama]\nurl = "http://remote:11434"\nsummary_model = "mistral:7b"\n'
+        )
+        result = _load_file(config_file)
+        assert result["ollama_url"] == "http://remote:11434"
+        assert result["summary_model"] == "mistral:7b"
+
+    def test_yaml_loading(self, tmp_path):
+        config_file = tmp_path / "config.yaml"
+        config_file.write_text(
+            "ollama:\n  url: http://remote:11434\n  summary_model: mistral:7b\n"
+        )
+        result = _load_file(config_file)
+        assert result["ollama_url"] == "http://remote:11434"
+        assert result["summary_model"] == "mistral:7b"
+
+    def test_malformed_toml_returns_empty(self, tmp_path):
+        config_file = tmp_path / "config.toml"
+        config_file.write_text("invalid toml {{{{")
+        result = _load_file(config_file)
+        assert result == {}
+
+    def test_malformed_yaml_returns_empty(self, tmp_path):
+        config_file = tmp_path / "config.yaml"
+        config_file.write_text(":\n  :\n    - [invalid")
+        result = _load_file(config_file)
+        assert result == {}
+
+    def test_unsupported_extension_returns_empty(self, tmp_path):
+        config_file = tmp_path / "config.ini"
+        config_file.write_text("[section]\nkey=value")
+        result = _load_file(config_file)
+        assert result == {}
+
+    def test_partial_config(self, tmp_path):
+        config_file = tmp_path / "config.toml"
+        config_file.write_text('[search]\nrrf_k = 100\n')
+        result = _load_file(config_file)
+        assert result == {"rrf_k": 100}
+        assert "ollama_url" not in result
+
+
+class TestLoadEnvVars:
+    def test_all_env_vars(self, monkeypatch):
+        monkeypatch.setenv("CEX_OLLAMA_URL", "http://gpu:11434")
+        monkeypatch.setenv("CEX_OLLAMA_SUMMARY_MODEL", "mistral:7b")
+        monkeypatch.setenv("CEX_OLLAMA_EMBEDDING_MODEL", "nomic-embed-text")
+        monkeypatch.setenv("CEX_OLLAMA_EMBEDDING_DIM", "768")
+        monkeypatch.setenv("CEX_STORAGE_DB_PATH", "/tmp/test.db")
+        monkeypatch.setenv("CEX_STORAGE_VECTOR_PATH", "/tmp/vectors")
+        monkeypatch.setenv("CEX_SEARCH_RRF_K", "30")
+        monkeypatch.setenv("CEX_SEARCH_RESULT_LIMIT", "50")
+
+        result = _load_env_vars()
+        assert result["ollama_url"] == "http://gpu:11434"
+        assert result["summary_model"] == "mistral:7b"
+        assert result["embedding_model"] == "nomic-embed-text"
+        assert result["embedding_dim"] == 768
+        assert result["db_path"] == "/tmp/test.db"
+        assert result["vector_path"] == "/tmp/vectors"
+        assert result["rrf_k"] == 30
+        assert result["result_limit"] == 50
+
+    def test_no_env_vars(self, monkeypatch):
+        for var in ["CEX_OLLAMA_URL", "CEX_OLLAMA_SUMMARY_MODEL", "CEX_OLLAMA_EMBEDDING_MODEL",
+                     "CEX_OLLAMA_EMBEDDING_DIM", "CEX_STORAGE_DB_PATH", "CEX_STORAGE_VECTOR_PATH",
+                     "CEX_SEARCH_RRF_K", "CEX_SEARCH_RESULT_LIMIT"]:
+            monkeypatch.delenv(var, raising=False)
+        result = _load_env_vars()
+        assert result == {}
+
+    def test_invalid_int_ignored(self, monkeypatch):
+        monkeypatch.setenv("CEX_OLLAMA_EMBEDDING_DIM", "not_a_number")
+        result = _load_env_vars()
+        assert "embedding_dim" not in result
+
+
+class TestResolveConfig:
+    def test_defaults_only(self):
+        config, sources = _resolve_config({}, {})
+        assert config.ollama_url == "http://localhost:11434"
+        assert all(s == ConfigSource.DEFAULT for s in sources.values())
+
+    def test_file_overrides_default(self):
+        config, sources = _resolve_config({"summary_model": "mistral:7b"}, {})
+        assert config.summary_model == "mistral:7b"
+        assert sources["summary_model"] == ConfigSource.FILE
+        assert sources["ollama_url"] == ConfigSource.DEFAULT
+
+    def test_env_overrides_file(self):
+        config, sources = _resolve_config(
+            {"summary_model": "mistral:7b"},
+            {"summary_model": "llama3:8b"},
+        )
+        assert config.summary_model == "llama3:8b"
+        assert sources["summary_model"] == ConfigSource.ENV
+
+    def test_source_tracking(self):
+        config, sources = _resolve_config(
+            {"rrf_k": 100},
+            {"result_limit": 50},
+        )
+        assert sources["rrf_k"] == ConfigSource.FILE
+        assert sources["result_limit"] == ConfigSource.ENV
+        assert sources["ollama_url"] == ConfigSource.DEFAULT
+
+
+class TestValidateConfig:
+    def test_valid_config(self):
+        _validate_config(AppConfig())  # should not raise
+
+    def test_invalid_embedding_dim(self):
+        with pytest.raises(ValueError, match="Embedding dimension"):
+            _validate_config(AppConfig(embedding_dim=0))
+
+    def test_negative_rrf_k(self):
+        with pytest.raises(ValueError, match="fusion constant"):
+            _validate_config(AppConfig(rrf_k=-1))
+
+    def test_result_limit_zero(self):
+        with pytest.raises(ValueError, match="Result limit"):
+            _validate_config(AppConfig(result_limit=0))
+
+    def test_result_limit_too_high(self):
+        with pytest.raises(ValueError, match="Result limit"):
+            _validate_config(AppConfig(result_limit=5000))
+
+    def test_bad_url(self):
+        with pytest.raises(ValueError, match="http://"):
+            _validate_config(AppConfig(ollama_url="ftp://bad"))
+
+
+class TestDiscoverConfigFile:
+    def test_finds_toml(self, tmp_path):
+        (tmp_path / "config.toml").write_text("[ollama]\n")
+        result = _discover_config_file(tmp_path)
+        assert result == tmp_path / "config.toml"
+
+    def test_finds_yaml(self, tmp_path):
+        (tmp_path / "config.yaml").write_text("ollama:\n  url: x\n")
+        result = _discover_config_file(tmp_path)
+        assert result == tmp_path / "config.yaml"
+
+    def test_toml_priority_over_yaml(self, tmp_path):
+        (tmp_path / "config.toml").write_text("[ollama]\n")
+        (tmp_path / "config.yaml").write_text("ollama:\n  url: x\n")
+        result = _discover_config_file(tmp_path)
+        assert result == tmp_path / "config.toml"
+
+    def test_no_config(self, tmp_path):
+        result = _discover_config_file(tmp_path)
+        assert result is None
+
+    def test_missing_dir(self, tmp_path):
+        result = _discover_config_file(tmp_path / "nonexistent")
+        assert result is None
+
+
+class TestWriteDefaultConfig:
+    def test_toml_output(self, tmp_path):
+        path = tmp_path / "config.toml"
+        write_default_config(path, fmt="toml")
+        assert path.exists()
+        data = tomllib.loads(path.read_text())
+        assert data["ollama"]["url"] == "http://localhost:11434"
+        assert data["ollama"]["embedding_dim"] == 4096
+        assert data["search"]["rrf_k"] == 60
+
+    def test_yaml_output(self, tmp_path):
+        import yaml
+
+        path = tmp_path / "config.yaml"
+        write_default_config(path, fmt="yaml")
+        assert path.exists()
+        data = yaml.safe_load(path.read_text())
+        assert data["ollama"]["url"] == "http://localhost:11434"
+        assert data["search"]["result_limit"] == 20
+
+    def test_creates_parent_dirs(self, tmp_path):
+        path = tmp_path / "deep" / "nested" / "config.toml"
+        write_default_config(path, fmt="toml")
+        assert path.exists()
+
+
+class TestGetConfigSingleton:
+    def test_returns_defaults_without_file(self, monkeypatch, tmp_path):
+        monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
+        for var in ["CEX_OLLAMA_URL", "CEX_OLLAMA_SUMMARY_MODEL", "CEX_OLLAMA_EMBEDDING_MODEL",
+                     "CEX_OLLAMA_EMBEDDING_DIM", "CEX_STORAGE_DB_PATH", "CEX_STORAGE_VECTOR_PATH",
+                     "CEX_SEARCH_RRF_K", "CEX_SEARCH_RESULT_LIMIT"]:
+            monkeypatch.delenv(var, raising=False)
+        reset_config()
+        cfg = get_config()
+        assert cfg.ollama_url == "http://localhost:11434"
+        assert cfg.summary_model == "llama3.2:3b"
+
+    def test_reads_from_file(self, monkeypatch, tmp_path):
+        config_dir = tmp_path / "code-explore"
+        config_dir.mkdir()
+        (config_dir / "config.toml").write_text(
+            '[ollama]\nsummary_model = "phi3:mini"\n'
+        )
+        monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
+        for var in ["CEX_OLLAMA_URL", "CEX_OLLAMA_SUMMARY_MODEL"]:
+            monkeypatch.delenv(var, raising=False)
+        reset_config()
+        cfg = get_config()
+        assert cfg.summary_model == "phi3:mini"
+
+    def test_env_overrides_file(self, monkeypatch, tmp_path):
+        config_dir = tmp_path / "code-explore"
+        config_dir.mkdir()
+        (config_dir / "config.toml").write_text(
+            '[ollama]\nsummary_model = "phi3:mini"\n'
+        )
+        monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
+        monkeypatch.setenv("CEX_OLLAMA_SUMMARY_MODEL", "gemma:2b")
+        reset_config()
+        cfg = get_config()
+        assert cfg.summary_model == "gemma:2b"
+
+
+class TestGetResolvedSettings:
+    def test_returns_all_settings(self, monkeypatch, tmp_path):
+        monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
+        for var in ["CEX_OLLAMA_URL", "CEX_OLLAMA_SUMMARY_MODEL", "CEX_OLLAMA_EMBEDDING_MODEL",
+                     "CEX_OLLAMA_EMBEDDING_DIM", "CEX_STORAGE_DB_PATH", "CEX_STORAGE_VECTOR_PATH",
+                     "CEX_SEARCH_RRF_K", "CEX_SEARCH_RESULT_LIMIT"]:
+            monkeypatch.delenv(var, raising=False)
+        reset_config()
+        settings = get_resolved_settings()
+        assert len(settings) == 8
+        names = {s.name for s in settings}
+        assert "Ollama URL" in names
+        assert "Embedding model" in names
+        assert "Result limit" in names
+
+    def test_source_tracking(self, monkeypatch, tmp_path):
+        config_dir = tmp_path / "code-explore"
+        config_dir.mkdir()
+        (config_dir / "config.toml").write_text('[search]\nrrf_k = 100\n')
+        monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
+        monkeypatch.setenv("CEX_SEARCH_RESULT_LIMIT", "50")
+        for var in ["CEX_OLLAMA_URL", "CEX_OLLAMA_SUMMARY_MODEL", "CEX_OLLAMA_EMBEDDING_MODEL",
+                     "CEX_OLLAMA_EMBEDDING_DIM", "CEX_STORAGE_DB_PATH", "CEX_STORAGE_VECTOR_PATH",
+                     "CEX_SEARCH_RRF_K"]:
+            monkeypatch.delenv(var, raising=False)
+        reset_config()
+        settings = get_resolved_settings()
+        by_name = {s.name: s for s in settings}
+        assert by_name["Search fusion (k)"].source == ConfigSource.FILE
+        assert by_name["Result limit"].source == ConfigSource.ENV
+        assert by_name["Ollama URL"].source == ConfigSource.DEFAULT

code_explore-0.2.0/tests/test_config_cli.py

@@ -0,0 +1,121 @@
+"""Tests for CLI config commands."""
+
+from pathlib import Path
+
+import pytest
+from typer.testing import CliRunner
+
+from code_explore.cli.main import app
+from code_explore.config import reset_config
+
+runner = CliRunner()
+
+
+class TestConfigShow:
+    def test_exit_code(self, monkeypatch, tmp_path):
+        monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
+        reset_config()
+        result = runner.invoke(app, ["config", "show"])
+        assert result.exit_code == 0
+
+    def test_contains_all_settings(self, monkeypatch, tmp_path):
+        monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
+        reset_config()
+        result = runner.invoke(app, ["config", "show"])
+        assert "Ollama URL" in result.stdout
+        assert "Summary model" in result.stdout
+        assert "Embedding model" in result.stdout
+        assert "Embedding dimension" in result.stdout
+        assert "Database path" in result.stdout
+        assert "Vector store path" in result.stdout
+        assert "Search fusion" in result.stdout
+        assert "Result limit" in result.stdout
+
+    def test_shows_default_source(self, monkeypatch, tmp_path):
+        monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
+        reset_config()
+        result = runner.invoke(app, ["config", "show"])
+        assert "default" in result.stdout
+
+
+class TestConfigInit:
+    def test_creates_toml(self, monkeypatch, tmp_path):
+        monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
+        reset_config()
+        result = runner.invoke(app, ["config", "init"])
+        assert result.exit_code == 0
+        assert (tmp_path / "code-explore" / "config.toml").exists()
+
+    def test_creates_yaml(self, monkeypatch, tmp_path):
+        monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
+        reset_config()
+        result = runner.invoke(app, ["config", "init", "--format", "yaml"])
+        assert result.exit_code == 0
+        assert (tmp_path / "code-explore" / "config.yaml").exists()
+
+    def test_fails_if_exists(self, monkeypatch, tmp_path):
+        config_dir = tmp_path / "code-explore"
+        config_dir.mkdir()
+        (config_dir / "config.toml").write_text("[ollama]\n")
+        monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
+        reset_config()
+        result = runner.invoke(app, ["config", "init"])
+        assert result.exit_code == 1
+        assert "already exists" in result.stdout
+
+    def test_force_overwrites(self, monkeypatch, tmp_path):
+        config_dir = tmp_path / "code-explore"
+        config_dir.mkdir()
+        (config_dir / "config.toml").write_text("[ollama]\n")
+        monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
+        reset_config()
+        result = runner.invoke(app, ["config", "init", "--force"])
+        assert result.exit_code == 0
+        content = (config_dir / "config.toml").read_text()
+        assert "localhost" in content
+
+
+class TestConfigReset:
+    def test_deletes_config_file(self, monkeypatch, tmp_path):
+        config_dir = tmp_path / "code-explore"
+        config_dir.mkdir()
+        config_file = config_dir / "config.toml"
+        config_file.write_text("[ollama]\n")
+        monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
+        reset_config()
+        result = runner.invoke(app, ["config", "reset", "--yes"])
+        assert result.exit_code == 0
+        assert not config_file.exists()
+
+    def test_no_file_to_reset(self, monkeypatch, tmp_path):
+        monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
+        reset_config()
+        result = runner.invoke(app, ["config", "reset", "--yes"])
+        assert result.exit_code == 0
+        assert "defaults" in result.stdout.lower()
+
+
+class TestConfigPath:
+    def test_shows_path(self, monkeypatch, tmp_path):
+        monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
+        reset_config()
+        result = runner.invoke(app, ["config", "path"])
+        assert result.exit_code == 0
+        assert "code-explore" in result.stdout
+
+    def test_shows_existing_path(self, monkeypatch, tmp_path):
+        config_dir = tmp_path / "code-explore"
+        config_dir.mkdir()
+        (config_dir / "config.toml").write_text("[ollama]\n")
+        monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
+        reset_config()
+        result = runner.invoke(app, ["config", "path"])
+        assert result.exit_code == 0
+        assert "config.toml" in result.stdout
+
+
+class TestConfigHelp:
+    def test_config_help(self):
+        result = runner.invoke(app, ["config", "--help"])
+        assert result.exit_code == 0
+        assert "config" in result.stdout.lower()

{code_explore-0.1.0 → code_explore-0.2.0}/tests/test_search_hybrid.py

@@ -1,7 +1,8 @@
 """Tests for hybrid search / reciprocal rank fusion."""
 
+from code_explore.config import reset_config
 from code_explore.models import Project, QualityMetrics, SearchResult
-from code_explore.search.hybrid import _reciprocal_rank_fusion, RRF_K
+from code_explore.search.hybrid import _reciprocal_rank_fusion
 
 
 def _make_result(pid: str, name: str, score: float, match_type: str = "fulltext") -> SearchResult:
@@ -44,7 +45,7 @@ class TestReciprocalRankFusion:
         # "a" appears in both → should be ranked first (higher combined score)
         assert result[0].project.id == "a"
         # "a" gets score from both lists
-        expected_score_a = 1.0 / (RRF_K + 1) + 1.0 / (RRF_K + 1)
+        expected_score_a = 1.0 / (60 + 1) + 1.0 / (60 + 1)
         assert abs(result[0].score - expected_score_a) < 0.001
 
     def test_disjoint_results(self):