CONTRIBUTING.md [component] deterministic

Contributing to Sovereign Intelligence Stack

**Version:** 1.0.0 **Last Updated:** July 5, 2026 **Repository:** [sovereign-intelligence-stack](https://github.com/kliewerdaniel/sovereign-intelligence-stack)

---

Philosophy

The Sovereign Intelligence Stack is built on the principle that **intelligence is not the model. Intelligence is the accumulated decisions that shaped the model.**

Contributions should follow this principle. Every contribution should make the system smarter over time, not just faster.

---

Getting Started

Prerequisites

• Python 3.11+
• SQLite (usually pre-installed)
• Git
• A code editor or IDE

Setup

```bash # Clone the repository git clone https://github.com/kliewerdaniel/sovereign-intelligence-stack.git cd sovereign-intelligence-stack

Create a virtual environment python3 -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate

Install dependencies pip install -r requirements.txt

Run tests pytest tests/ ```

Project Structure

src/ ├── recipe_compiler/ # Layer 1: Recipe Compiler │ ├── models.py # Recipe dataclass │ ├── schema.py # SQLite schema with FTS5 │ ├── storage.py # CRUD operations │ └── api.py # FastAPI HTTP endpoints ├── signal_router/ # Layer 2: Signal Router │ ├── classifier.py # Signal classification │ └── router.py # Routing logic ├── evaluation/ # Layer 3: Evaluation Loop │ ├── definitions.py # Signal registry │ ├── generator.py # Test case generation │ ├── drifter.py # Drift detection │ └── loop.py # Evaluation loop ├── knowledge/ # Layer 4: Knowledge Systems │ ├── graph_store.py # Knowledge graph │ ├── vector_store.py # Vector embeddings │ └── graphrag.py # GraphRAG retrieval ├── memory/ # Layer 4: Persistent Memory │ ├── storage.py # Memory storage │ └── management.py # Memory lifecycle ├── observatory/ # Layer 5: Intelligence Observatory │ ├── timeline.py # Timeline generation │ ├── detectors.py # Pattern detection │ ├── reporter.py # Reporting │ └── visualizer.py # Visualization ├── tacit_judgment/ # Tacit Judgment Extractor │ ├── pipeline.py # Extraction pipeline │ ├── models.py # Session models │ └── api.py # HTTP endpoints ├── integration/ # Integration Layer │ ├── pipe.py # SovereignPipeline │ └── federated_sync.py # Federated sync └── shared/ # Shared Utilities ├── ollama_client.py # Ollama API client ├── chroma_client.py # ChromaDB client └── async_db.py # Async database operations

---

Contributing Guidelines

1. Code Style

Follow PEP 8 with these additional guidelines:

• **Type Hints:** Use type hints for all functions
• **Docstrings:** Use Google-style docstrings
• **Imports:** Use absolute imports, group by standard library, third-party, local
• **Naming:** Use snake_case for functions, PascalCase for classes
• **Comments:** Explain why, not what

**Example:**

python def calculate_drift_score(old_scores: List[float], new_scores: List[float]) -> float: """Calculate drift score between old and new evaluation scores. Args: old_scores: Previous evaluation scores new_scores: Current evaluation scores Returns: Drift score between 0.0 (no drift) and 1.0 (maximum drift) """ # Implementation here pass

2. Testing

All new code must include tests:

```bash # Run all tests pytest tests/

Run specific test pytest tests/test_recipe_compiler.py -v

Run with coverage pytest --cov=src tests/ ```

**Test Guidelines:**

• Write tests for all new features
• Write tests for all bug fixes
• Aim for >80% code coverage
• Use pytest fixtures for shared setup
• Mock external dependencies (Ollama, ChromaDB, etc.)

3. Documentation

All new features must include documentation:

• Update API.md for new endpoints
• Update README.md for new features
• Add docstrings for all public functions
• Add usage examples for complex features

4. Git Commits

Follow conventional commits:

bash git commit -m "feat: add signal classifier for expert tasks" git commit -m "fix: handle edge case in recipe storage" git commit -m "docs: update API documentation for v1.0" git commit -m "test: add tests for evaluation loop" git commit -m "refactor: simplify signal router logic"

**Commit Message Format:**

``` <type>(<scope>): <description>

[optional body]

[optional footer] ```

**Types:**

• feat — New feature
• fix — Bug fix
• docs — Documentation changes
• test — Test changes
• refactor — Code refactoring
• chore — Maintenance tasks
• perf — Performance improvements

5. Pull Requests

• **Title:** Clear and descriptive
• **Description:** Explain what, why, and how
• **Screenshots:** Include for UI changes
• **Tests:** All tests must pass
• **Documentation:** Update documentation

**PR Template:**

```markdown ## Description

Brief description of changes.

Type of Change

• [ ] Bug fix (non-breaking change that fixes an issue)
• [ ] New feature (non-breaking change that adds functionality)
• [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
• [ ] Documentation update

Checklist

- [ ] My code follows the project's code style - [ ] I have added tests that cover my changes - [ ] All new and existing tests passed - [ ] I have added documentation for my changes - [ ] My changes generate no new warnings ```

---

Development Workflow

1. Fork and Clone

bash git clone https://github.com/your-username/sovereign-intelligence-stack.git cd sovereign-intelligence-stack

2. Create a Branch

bash git checkout -b feature/your-feature-name # or git checkout -b fix/your-bug-fix-name

3. Make Changes

• Write code
• Write tests
• Run