Introduce install-time configuration system for Codira (hardware + plugins)

[marco0560]

Introduce install-time configuration system for Codira (hardware + plugins)

Status

• Type: feature / configuration
• Priority: medium-high

Summary

Introduce a configuration file generated at installation time, allowing users to tune Codira behavior based on:

• hardware (especially embeddings)
• plugin activation
• runtime preferences

Motivation

Codira behavior depends on:

• hardware capabilities (CPU, memory, embeddings cost)
• enabled analyzers/plugins
• workflow preferences

Currently, configuration is implicit or CLI-driven.

Goal

Provide a persistent, user-editable configuration layer that:

• is generated at install time
• can be modified by the user
• influences runtime behavior deterministically

Scope

Configuration file

• generated during install or first run
• stored in user config directory

Configurable aspects

• embeddings parameters (batch size, limits)
• plugin enable/disable
• default behaviors

Open question

• is this the correct place to configure plugins?
  • or should plugin configuration be separate?

Non-goals

• dynamic runtime reconfiguration
• complex UI for configuration

Design considerations

• configuration must be explicit and deterministic
• defaults must be safe
• CLI should override config when needed

Acceptance Criteria

• config file is generated automatically
• user can modify settings
• runtime behavior reflects configuration
• plugin activation can be controlled

Dependencies

• Deterministic Capability Contract, Canonical Ontology, and Analyzer Declarations #7 — Analyzer capability contract
• Decouple indexer from SQLite and make backend layer truly plugin-agnostic #8 — Backend decoupling

Notes

This feature improves:

• usability
• reproducibility
• adaptability across environments

[marco0560]

Comment: Configuration System Design Alignment

FACT

The current proposal is consistent with the defined Codira configuration architecture, with the following clarifications:

• A configuration file can be generated at install time OR first run without contradiction

• The system supports multi-level configuration:

  • system
  • user
  • repository
  • CLI overrides

• The issue correctly focuses on user-level configuration as the initial entry point

---

ASSUMPTION

• “install-time configuration” is intended as:

  • initial bootstrap of user config
  • not the only configuration layer

• Repository-level configuration (.codira/config.toml) is introduced later or independently

---

PROPOSAL

1. Clarify Scope (avoid ambiguity)

Replace:

"configuration file generated at installation time"

With:

"a user-level configuration file generated at installation time or first run"

---

2. Explicit Configuration Hierarchy

Add:

Configuration precedence (highest → lowest):

CLI flags
→ repository config (.codira/config.toml)
→ user config (~/.config/codira/config.toml or %APPDATA%\codira\config.toml)
→ system config (/etc/codira/config.toml or C:\ProgramData\codira\config.toml)
→ built-in defaults

This prevents future ambiguity and enforces determinism.

---

3. Plugin Configuration (open question resolution)

FACT

Plugins must be configurable within the main config system.

PROPOSAL

• Plugin activation: central config
• Plugin-specific settings: namespaced sections

Example:

[plugins]
enabled = ["analyzer-python", "backend-sqlite"]

[plugins.analyzer-python]
strict = true

Rationale

• avoids config fragmentation
• maintains single source of truth
• aligns with analyzer/backend architecture

---

4. Embeddings Configuration (extend scope)

The issue under-specifies embeddings.

PROPOSAL

Explicitly include:

• device selection (cpu/gpu/auto)
• thread control
• batch size
• memory limits

Example:

[embeddings]
enabled = false
device = "auto"
threads = 0
batch_size = 32

[embeddings.gpu]
device_id = 0
memory_limit_mb = 0

---

5. Add Required CLI Support

To satisfy acceptance criteria:

codira config init
codira config dump
codira config explain <key>
codira config validate

---

6. Add Missing Acceptance Criteria

PROPOSAL

Add:

• configuration precedence is deterministic and documented
• effective configuration can be inspected (config dump)
• origin of each value can be traced (config explain)
• configuration validation prevents invalid states

---

7. Non-Contradictions Confirmed

FACT

No contradictions detected between:

• install-time config generation
• multi-level configuration model
• CLI override principle
• deterministic behavior requirement

---

8. Minimal Adjustment Summary

PROPOSAL

Required changes are clarifications, not redesign:

1. clarify "install-time" → "user-level bootstrap"
2. document configuration hierarchy
3. define plugin configuration location (centralized)
4. expand embeddings section
5. include config CLI tooling
6. strengthen acceptance criteria

---

CONCLUSION

The issue is structurally sound and aligned with the planned configuration system.
Only precision improvements are required to avoid future ambiguity and contract drift.

Proposed Implementation Plan

Codira Configuration System — Implementation Plan

Status

• Type: implementation plan
• Scope: configuration system (multi-level, deterministic)
• Version target: post-v1.18.2
• MANDATORY CONSTRAINT: this issue is to be implemented on a separate branch

---

Overview

Introduce a deterministic, multi-level configuration system for Codira with:

• optional configuration (Codira works without config files)
• explicit override hierarchy
• full runtime control over behavior
• CLI-based introspection and management

---

Design Principles

• Optionality
  No configuration file required for normal operation

• Determinism
  Same inputs + same config → identical outputs

• Explicit precedence

CLI > repo > user > system > defaults

• Single source of truth (SOT)
  Defaults defined in code

• No hidden behavior
  Effective configuration must be inspectable

---

Configuration Locations

Linux

• System: /etc/codira/config.toml
• User: ~/.config/codira/config.toml
• Repo: <repo>/.codira/config.toml

Windows

• System: C:\ProgramData\codira\config.toml
• User: %APPDATA%\codira\config.toml
• Repo: <repo>\.codira\config.toml

---

Phases

---

Phase 0 — Foundations (Schema + Defaults)

Goal

Define authoritative schema and defaults

Tasks

• Define typed schema (dataclasses or equivalent)
• Include sections:
  • core
  • indexing
  • analyzers
  • backend
  • query
  • embeddings
  • plugins
• Implement default config (SOT)
• Implement validation layer:
  • type checks
  • allowed values enforcement

Output

• config_schema.py
• default_config.py

---

Phase 1 — Loader & Merge Engine

Goal

Deterministic multi-level resolution

Tasks

• Implement config discovery (system/user/repo)
• Implement TOML loader
• Implement merge engine:
  • order: defaults → system → user → repo → CLI
  • rules:
    • scalar → override
    • dict → deep merge
    • list → replace
• Produce immutable final config object

Output

• config_loader.py
• config_merge.py

---

Phase 2 — CLI Integration

Goal

Expose configuration to users

Commands

codira config init [--minimal|--full] [--force] [--profile NAME]
codira config dump [--level system|user|repo|effective]
codira config explain <key>
codira config validate

Tasks

• Implement command handlers
• Implement config init
  • create .codira/config.toml
• Implement config dump
• Implement config explain
• Implement config validate

Output

• CLI bindings
• command implementations

---

Phase 3 — Runtime Integration

Goal

Make config drive behavior

Tasks

• Inject config into:
  • indexing
  • analyzers
  • backend
  • query engine
  • embeddings
• Remove hardcoded values
• Enforce config-driven behavior

Output

• Config-aware subsystems

---

Phase 4 — Embeddings Integration

Goal

Hardware-aware execution

Tasks

• Implement device resolution:
  • auto → GPU if available → fallback CPU
• Implement thread resolution:
  • 0 → os.cpu_count()
• Enforce:
  • GPU constraints
  • memory limits
• Add debug logging for resolution decisions

Output

• Embeddings runtime adapter

---

Phase 5 — Plugin Configuration

Goal

Centralized plugin control

Tasks

• Integrate with plugin registry
• Support:
  • enable/disable plugins
  • namespaced plugin configuration
• Validate unknown plugins (error in strict mode)

Output

• plugin_config_adapter.py

---

Phase 6 — Validation & Safety

Goal

Prevent invalid states

Tasks

• Implement config validate
• Add:
  • unknown key detection
  • strict mode enforcement
• Add schema version handling

Output

• Validation module

---

Phase 7 — Testing

Goal

Guarantee determinism

Tasks

• Unit tests:
  • merge behavior
  • precedence
  • validation
• Integration tests:
  • CLI commands
  • config workflows
• Cross-platform tests:
  • path resolution (Linux/Windows)

Output

• Test suite

---

Phase 8 — Documentation

Goal

User and developer clarity

Tasks

• Document:
  • config hierarchy
  • schema reference
  • examples
• Generate default config snapshot
• Add CLI usage examples

Output

• docs/configuration.md

---

Phase 9 — Migration Strategy

Goal

Future-proof configuration

Tasks

• Introduce config_version
• Define migration hooks
• Define behavior for older configs

Output

• Migration policy

---

Embeddings Configuration Scope

Configuration must include:

• enable/disable embeddings
• model selection
• device (auto, cpu, gpu)
• thread count
• batch size
• GPU:
  • device id
  • memory limits

---

Plugin Configuration Model

[plugins]
enabled = ["plugin-name"]

[plugins.plugin-name]
key = value

---

Execution Order

Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5 → Phase 6 → Phase 7 → Phase 8 → Phase 9

---

Acceptance Criteria

• Config system is optional but fully functional
• Deterministic precedence is enforced
• Effective config is inspectable (dump)
• Config origin is traceable (explain)
• CLI overrides are respected
• Plugin activation is configurable
• Embeddings are hardware-aware and configurable
• Cross-platform behavior is consistent

---