Architecture

occam-gitignore is a hexagonal monorepo: one pure core plus thin adapters. Adapters depend on the core. The core depends on nothing.

┌─────────────────────────────────────────────────────────────┐
│                     occam-gitignore-core                    │
│                                                             │
│   generate(fingerprint, options, *, templates, rules_table) │
│        ↓ pure, deterministic, hash-verifiable               │
│        GitignoreOutput                                      │
└─────────────────────────────────────────────────────────────┘
            ▲              ▲              ▲             ▲
            │              │              │             │
        ┌───┴────┐   ┌─────┴────┐   ┌─────┴─────┐  ┌────┴─────┐
        │  CLI   │   │   API    │   │    MCP    │  │  Bench   │
        │ Typer  │   │ FastAPI  │   │  FastMCP  │  │ harness  │
        └────────┘   └──────────┘   └───────────┘  └──────────┘

The training package occam-gitignore-training is offline-only: it consumes JSONL records and produces a rules_table.json used by the core at runtime.

Packages

Package	Role	Dependencies
occam-gitignore-core	Pure generator, schema, ports, default fingerprinter	none
occam-gitignore-cli	Typer entry point	core, typer
occam-gitignore-api	FastAPI HTTP service	core, fastapi
occam-gitignore-mcp	MCP server (stdio, SSE, streamable-http)	core, mcp
occam-gitignore-training	Offline mining (lift, support, pair detection)	core
occam-gitignore-bench	Recall/precision/F1/stability/latency harness	core

Ports

Two protocols define everything the core needs:

class TemplateRepository(Protocol):
    def get(self, feature: Feature) -> tuple[Rule, ...]: ...
    def features(self) -> tuple[Feature, ...]: ...
    def version(self) -> str: ...

class RulesTable(Protocol):
    def extras_for(self, features: frozenset[Feature]) -> tuple[Rule, ...]: ...
    def version(self) -> str: ...

The core ships two adapters for each: FileSystemTemplateRepository / InMemoryTemplateRepository, and JsonRulesTable / InMemoryRulesTable.

Generation pipeline

1. Fingerprint the input tree. The default detector recognises 11 features: python, node, go, rust, docker, terraform, jupyter, java, ruby, csharp, swift. Detection is pure (path matching only).
2. Inject implicit features. When any feature matches and the template repository provides a common feature, OS/IDE patterns are added.
3. Collect rules from templates, then from the rules table, then from user extras — in that fixed precedence order.
4. Stable dedupe. The first occurrence wins (preserves provenance from the highest-priority source). Output sorted by (source, pattern).
5. Render. Optional header, optional section comments, optional provenance suffix per rule. Output finalised with a trailing newline.
6. Hash. sha256(content) is computed and returned in output_hash.

The whole pipeline is one pure function — no I/O, no clock, no allocations that depend on PYTHONHASHSEED.