diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md
new file mode 100644
index 0000000..263ae59
--- /dev/null
+++ b/.planning/PROJECT.md
@@ -0,0 +1,77 @@
+# Case-Insensitive Prefix Search for folio-python
+
+## What This Is
+
+Adding case-insensitive prefix search to the folio-python library's `search_by_prefix()` method. Currently, prefix search is case-sensitive because the underlying `marisa-trie` stores labels in their original case (e.g., "Securities Fraud", "DUI", "M&A Practice Components"), but all realistic callers lowercase their input before searching — causing 100% silent miss rates.
+
+## Core Value
+
+Prefix search must return correct results regardless of input casing — `search_by_prefix("securit")` must match "Securities Fraud" just as `search_by_prefix("Securit")` does today.
+
+## Requirements
+
+### Validated
+
+- Existing case-sensitive `search_by_prefix()` works correctly for exact-case input — existing
+- `search_by_label()` already handles case insensitivity via rapidfuzz — existing
+- Trie is built from both `label_to_index` and `alt_label_to_index` keys — existing
+
+### Active
+
+- [ ] Build parallel lowercase `marisa-trie` alongside existing case-sensitive trie
+- [ ] Add `case_sensitive` parameter to `search_by_prefix()` defaulting to `False`
+- [ ] Fix pure-Python fallback path to also support case-insensitive search
+- [ ] Normalize prefix cache to share entries across case variants when case-insensitive
+- [ ] Map lowercase trie keys back to original `OWLClass` objects correctly
+- [ ] Add tests covering case-insensitive prefix search (lowercase, UPPERCASE, mixed, acronyms like "DUI", symbols like "M&A")
+
+### Out of Scope
+
+- Changing `search_by_label()` behavior — already case-insensitive
+- Unicode normalization beyond `.lower()` — no evidence of non-ASCII labels in FOLIO
+- Removing the existing case-sensitive trie — preserved via `case_sensitive=True` parameter
+
+## Context
+
+- **Upstream issue:** alea-institute/folio-python#15
+- **Maintainer approval:** @mjbommar confirmed Option 1 (parallel lowercase trie) in issue comments
+- **Impact:** folio-mapper's Area of Law branch returns only 1 candidate instead of 5+ due to this bug
+- **Existing workaround:** folio-mapper tries both `.capitalize()` and lowercase, but fails for "DUI", "M&A", "IP" edge cases
+- **Library size:** ~18K FOLIO concepts — memory is not a constraint for a second trie
+- **Trie location:** `graph.py:1004-1012` builds the trie during `_load_folio()`
+- **Search location:** `graph.py:1289-1333` implements `search_by_prefix()`
+
+## Constraints
+
+- **Backward compatibility**: Existing `search_by_prefix("Securit")` must continue to work — the new `case_sensitive=False` default returns a superset of what `case_sensitive=True` would return
+- **No new dependencies**: Only uses existing `marisa_trie` (already a dependency)
+- **Branch strategy**: Feature branch `feature/case-insensitive-prefix` targeting `main`
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| Option 1: Parallel lowercase trie | Cheap in memory (~18K concepts), O(prefix) lookup, simple mapping back to OWLClass via lowercase→original label dict | -- Pending |
+| `case_sensitive=False` default | Matches user expectation — all realistic callers lowercase input | -- Pending |
+| Shared prefix cache (normalized to lowercase) | Avoids duplicate cache entries for "securit" vs "Securit" when case-insensitive | -- Pending |
+| Fix both trie and pure-Python fallback | Consistent behavior regardless of whether marisa_trie is installed | -- Pending |
+
+## Evolution
+
+This document evolves at phase transitions and milestone boundaries.
+
+**After each phase transition** (via `/gsd-transition`):
+1. Requirements invalidated? -> Move to Out of Scope with reason
+2. Requirements validated? -> Move to Validated with phase reference
+3. New requirements emerged? -> Add to Active
+4. Decisions to log? -> Add to Key Decisions
+5. "What This Is" still accurate? -> Update if drifted
+
+**After each milestone** (via `/gsd-complete-milestone`):
+1. Full review of all sections
+2. Core Value check — still the right priority?
+3. Audit Out of Scope — reasons still valid?
+4. Update Context with current state
+
+---
+*Last updated: 2026-04-07 after initialization*
diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md
new file mode 100644
index 0000000..97f30cb
--- /dev/null
+++ b/.planning/REQUIREMENTS.md
@@ -0,0 +1,96 @@
+# Requirements: Case-Insensitive Prefix Search
+
+**Defined:** 2026-04-07
+**Core Value:** Prefix search must return correct results regardless of input casing
+
+## v1 Requirements
+
+### Data Structures
+
+- [ ] **DS-01**: FOLIOGraph declares `_lowercase_label_trie` attribute (parallel `marisa_trie.Trie` with casefolded keys)
+- [ ] **DS-02**: FOLIOGraph declares `_lowercase_to_original` attribute (`Dict[str, List[str]]` mapping casefolded labels to original-case labels)
+- [ ] **DS-03**: FOLIOGraph declares `_ci_prefix_cache` attribute (separate cache for case-insensitive queries)
+
+### Index Building
+
+- [ ] **IDX-01**: `parse_owl()` builds `_lowercase_to_original` dict using `defaultdict(list)` from both `label_to_index` and `alt_label_to_index` keys with `casefold()`
+- [ ] **IDX-02**: `parse_owl()` builds `_lowercase_label_trie` from `_lowercase_to_original.keys()` (deduplicated by construction)
+- [ ] **IDX-03**: `parse_owl()` clears `_prefix_cache` and `_ci_prefix_cache` at start of trie-building block (fixes pre-existing `refresh()` staleness)
+
+### Search API
+
+- [ ] **API-01**: `search_by_prefix()` accepts `case_sensitive: bool = False` parameter
+- [ ] **API-02**: When `case_sensitive=False`, queries the lowercase trie with `prefix.casefold()`
+- [ ] **API-03**: When `case_sensitive=True`, queries the existing trie with original prefix (preserves backward compat)
+- [ ] **API-04**: Case-insensitive results resolve through bridge dict → `label_to_index`/`alt_label_to_index` → `OWLClass`
+- [ ] **API-05**: Results are deduplicated by IRI index using a `seen` set (prevents duplicates from lowercase collisions)
+- [ ] **API-06**: Case-insensitive queries use `_ci_prefix_cache` keyed by `prefix.casefold()`
+
+### Fallback Parity
+
+- [ ] **FB-01**: Pure-Python fallback path (when `marisa_trie` is not installed) supports `case_sensitive` parameter
+- [ ] **FB-02**: Pure-Python fallback applies `casefold()` to both query prefix and labels when `case_sensitive=False`
+
+### Tests
+
+- [ ] **TEST-01**: Test case-insensitive search returns results for lowercase input (e.g., `"securit"` matches "Securities Fraud")
+- [ ] **TEST-02**: Test case-insensitive search handles acronyms (e.g., `"dui"` matches "DUI")
+- [ ] **TEST-03**: Test `case_sensitive=True` preserves original behavior (e.g., `"securit"` returns nothing, `"Securit"` returns results)
+- [ ] **TEST-04**: Test no duplicate OWLClass objects in results
+- [ ] **TEST-05**: Test existing `test_search_prefix` still passes (backward compat — "Mich" result ordering)
+- [ ] **TEST-06**: Test pure-Python fallback produces same results as trie path
+
+## v2 Requirements
+
+### Extended Normalization
+
+- **NORM-01**: NFKD Unicode normalization for non-ASCII labels
+- **NORM-02**: Accent/diacritic stripping for broader matching
+
+### Prefix Length
+
+- **LEN-01**: Lower `MIN_PREFIX_LENGTH` to 2 for short acronyms ("IP", "DK", "EU")
+
+## Out of Scope
+
+| Feature | Reason |
+|---------|--------|
+| Locale-aware case folding | Python 3 `casefold()` is sufficient; FOLIO labels are English |
+| Fuzzy prefix matching | `search_by_label()` already covers fuzzy via rapidfuzz |
+| Changing `search_by_label()` | Already case-insensitive |
+| Removing case-sensitive trie | Preserved via `case_sensitive=True` parameter |
+| `MIN_PREFIX_LENGTH` change | Separate concern, keep at 3 for this PR |
+
+## Traceability
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| DS-01 | Phase 1 | Pending |
+| DS-02 | Phase 1 | Pending |
+| DS-03 | Phase 1 | Pending |
+| IDX-01 | Phase 2 | Pending |
+| IDX-02 | Phase 2 | Pending |
+| IDX-03 | Phase 2 | Pending |
+| API-01 | Phase 3 | Pending |
+| API-02 | Phase 3 | Pending |
+| API-03 | Phase 3 | Pending |
+| API-04 | Phase 3 | Pending |
+| API-05 | Phase 3 | Pending |
+| API-06 | Phase 3 | Pending |
+| FB-01 | Phase 3 | Pending |
+| FB-02 | Phase 3 | Pending |
+| TEST-01 | Phase 4 | Pending |
+| TEST-02 | Phase 4 | Pending |
+| TEST-03 | Phase 4 | Pending |
+| TEST-04 | Phase 4 | Pending |
+| TEST-05 | Phase 4 | Pending |
+| TEST-06 | Phase 4 | Pending |
+
+**Coverage:**
+- v1 requirements: 20 total
+- Mapped to phases: 20
+- Unmapped: 0
+
+---
+*Requirements defined: 2026-04-07*
+*Last updated: 2026-04-07 after initial definition*
diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md
new file mode 100644
index 0000000..7dcdfee
--- /dev/null
+++ b/.planning/ROADMAP.md
@@ -0,0 +1,79 @@
+# Roadmap: Case-Insensitive Prefix Search
+
+## Overview
+
+This roadmap delivers case-insensitive prefix search for folio-python's `search_by_prefix()` method. The work progresses from declaring new data structures, through building parallel indexes, to modifying search behavior, and finally validating correctness with comprehensive tests. Each phase builds on the previous one, with the first two phases introducing zero behavioral change and Phase 3 delivering the actual feature flip.
+
+## Phases
+
+**Phase Numbering:**
+- Integer phases (1, 2, 3): Planned milestone work
+- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
+
+Decimal phases appear between their surrounding integers in numeric order.
+
+- [ ] **Phase 1: Data Structure Declarations** - Declare new attributes on FOLIOGraph for lowercase trie, bridge dict, and CI cache
+- [ ] **Phase 2: Index Building** - Build the parallel lowercase trie and bridge dict during parse_owl()
+- [ ] **Phase 3: Search API and Fallback** - Wire case-insensitive search through both trie and pure-Python paths
+- [ ] **Phase 4: Test Suite** - Validate correctness, backward compatibility, and edge cases
+
+## Phase Details
+
+### Phase 1: Data Structure Declarations
+**Goal**: FOLIOGraph has all new attributes declared so subsequent phases can populate and query them
+**Depends on**: Nothing (first phase)
+**Requirements**: DS-01, DS-02, DS-03
+**Success Criteria** (what must be TRUE):
+ 1. FOLIOGraph instances have a `_lowercase_label_trie` attribute initialized to None or empty
+ 2. FOLIOGraph instances have a `_lowercase_to_original` dict attribute initialized to empty
+ 3. FOLIOGraph instances have a `_ci_prefix_cache` dict attribute initialized to empty
+ 4. Existing tests still pass with no behavioral change
+**Plans**: TBD
+
+### Phase 2: Index Building
+**Goal**: parse_owl() populates the lowercase trie and bridge dict so they are ready for queries after loading
+**Depends on**: Phase 1
+**Requirements**: IDX-01, IDX-02, IDX-03
+**Success Criteria** (what must be TRUE):
+ 1. After parse_owl() completes, `_lowercase_to_original` maps every casefolded label/altLabel to its original-case variant(s)
+ 2. After parse_owl() completes, `_lowercase_label_trie` contains all keys from `_lowercase_to_original`
+ 3. Both `_prefix_cache` and `_ci_prefix_cache` are cleared at the start of the trie-building block (fixing pre-existing refresh() staleness)
+ 4. Existing tests still pass with no behavioral change
+**Plans**: TBD
+
+### Phase 3: Search API and Fallback
+**Goal**: Users can call search_by_prefix() with any casing and get correct results
+**Depends on**: Phase 2
+**Requirements**: API-01, API-02, API-03, API-04, API-05, API-06, FB-01, FB-02
+**Success Criteria** (what must be TRUE):
+ 1. `search_by_prefix("securit")` returns results including "Securities Fraud" (lowercase input matches title-case labels)
+ 2. `search_by_prefix("Securit", case_sensitive=True)` returns the same results as before this change (backward compat)
+ 3. `search_by_prefix("dui")` returns results including "DUI" (acronym case insensitivity)
+ 4. No duplicate OWLClass objects appear in any result set
+ 5. When marisa_trie is not installed, the pure-Python fallback produces equivalent case-insensitive results
+**Plans**: TBD
+
+### Phase 4: Test Suite
+**Goal**: Automated tests prove correctness, backward compatibility, and edge case handling
+**Depends on**: Phase 3
+**Requirements**: TEST-01, TEST-02, TEST-03, TEST-04, TEST-05, TEST-06
+**Success Criteria** (what must be TRUE):
+ 1. A test asserts lowercase prefix input returns correct OWLClass results (TEST-01)
+ 2. A test asserts acronym queries like "dui" match their uppercase labels (TEST-02)
+ 3. A test asserts case_sensitive=True preserves original behavior -- "securit" returns nothing, "Securit" returns results (TEST-03)
+ 4. A test asserts no duplicate OWLClass objects in results (TEST-04)
+ 5. The existing `test_search_prefix` ("Mich" ordering) still passes unchanged (TEST-05)
+ 6. A test asserts pure-Python fallback produces same results as the trie path (TEST-06)
+**Plans**: TBD
+
+## Progress
+
+**Execution Order:**
+Phases execute in numeric order: 1 -> 2 -> 3 -> 4
+
+| Phase | Plans Complete | Status | Completed |
+|-------|----------------|--------|-----------|
+| 1. Data Structure Declarations | 0/0 | Not started | - |
+| 2. Index Building | 0/0 | Not started | - |
+| 3. Search API and Fallback | 0/0 | Not started | - |
+| 4. Test Suite | 0/0 | Not started | - |
diff --git a/.planning/STATE.md b/.planning/STATE.md
new file mode 100644
index 0000000..e60f773
--- /dev/null
+++ b/.planning/STATE.md
@@ -0,0 +1,68 @@
+# Project State
+
+## Project Reference
+
+See: .planning/PROJECT.md (updated 2026-04-07)
+
+**Core value:** Prefix search must return correct results regardless of input casing
+**Current focus:** Phase 1 - Data Structure Declarations
+
+## Current Position
+
+Phase: 1 of 4 (Data Structure Declarations)
+Plan: 0 of 0 in current phase
+Status: Ready to plan
+Last activity: 2026-04-08 - Completed quick task 260408-9yz: Address PR #16 review feedback
+
+Progress: [░░░░░░░░░░] 0%
+
+## Performance Metrics
+
+**Velocity:**
+- Total plans completed: 0
+- Average duration: -
+- Total execution time: 0 hours
+
+**By Phase:**
+
+| Phase | Plans | Total | Avg/Plan |
+|-------|-------|-------|----------|
+| - | - | - | - |
+
+**Recent Trend:**
+- Last 5 plans: -
+- Trend: -
+
+*Updated after each plan completion*
+
+## Accumulated Context
+
+### Decisions
+
+Decisions are logged in PROJECT.md Key Decisions table.
+Recent decisions affecting current work:
+
+- Parallel lowercase trie approach confirmed by maintainer @mjbommar
+- casefold() over lower() for Unicode correctness
+- Separate _ci_prefix_cache to avoid heisenbug with shared cache
+
+### Pending Todos
+
+None yet.
+
+### Blockers/Concerns
+
+- MIN_PREFIX_LENGTH=3 filters out 2-char queries like "IP" -- documented as v2 scope (LEN-01)
+- Pre-existing _prefix_cache staleness in refresh() -- will be fixed in Phase 2 (IDX-03)
+
+### Quick Tasks Completed
+
+| # | Description | Date | Commit | Directory |
+|---|-------------|------|--------|-----------|
+| 260408-9yz | Address PR #16 review feedback: mechanical cleanups, dedup-with-tiebreak on both paths, label-over-alt-label ranking tweak | 2026-04-08 | 4b8262a | [260408-9yz-address-pr-16-review-feedback-mechanical](./quick/260408-9yz-address-pr-16-review-feedback-mechanical/) |
+
+## Session Continuity
+
+Last session: 2026-04-07
+Stopped at: Roadmap creation complete
+Resume file: None
diff --git a/.planning/codebase/ARCHITECTURE.md b/.planning/codebase/ARCHITECTURE.md
new file mode 100644
index 0000000..0ebb2e3
--- /dev/null
+++ b/.planning/codebase/ARCHITECTURE.md
@@ -0,0 +1,162 @@
+# Architecture
+
+**Analysis Date:** 2026-04-07
+
+## Pattern Overview
+
+**Overall:** Single-responsibility ontology service with a clear data loading, parsing, and query layer.
+
+**Key Characteristics:**
+- Monolithic `FOLIO` class serves as the main orchestrator for ontology access and querying
+- Data layer separates domain models (`OWLClass`, `OWLObjectProperty`) from the graph structure
+- Pluggable external data sources (GitHub or HTTP URL)
+- Optional search features using specialized indices (trie-based prefix search, fuzzy matching)
+- Client-agnostic LLM integration for semantic search
+
+## Layers
+
+**Data Models:**
+- Purpose: Define domain structures for OWL ontology entities
+- Location: `folio/models.py`
+- Contains: `OWLClass`, `OWLObjectProperty` (Pydantic BaseModel classes), namespace map (`NSMAP`)
+- Depends on: `pydantic`, `lxml` (for serialization)
+- Used by: `folio/graph.py` during parsing and data access
+
+**Configuration:**
+- Purpose: Manage source and caching configuration
+- Location: `folio/config.py`
+- Contains: `FOLIOConfiguration` class, default constants for GitHub/HTTP sources, cache paths
+- Depends on: `pydantic` for model validation
+- Used by: `folio/graph.py` during initialization
+
+**Logging:**
+- Purpose: Provide standardized logger instances
+- Location: `folio/logger.py`
+- Contains: `get_logger()` function that returns configured `logging.Logger` instances
+- Depends on: Standard `logging` module
+- Used by: All modules for debug/warning output
+
+**Core Graph Service:**
+- Purpose: Load, parse, index, and query the FOLIO ontology
+- Location: `folio/graph.py`
+- Contains: `FOLIO` class (main orchestrator), `FOLIOTypes` enum, type mapping constants
+- Depends on: `lxml.etree`, `httpx`, `pydantic`, optionally `rapidfuzz`, `marisa_trie`, `alea_llm_client`
+- Used by: Public API exported from `folio/__init__.py`
+
+## Data Flow
+
+**Initialization Flow:**
+
+1. **Create FOLIO instance** → `FOLIO.__init__()` captures source config (github/http, caching preference, LLM instance)
+2. **Load OWL file** → `FOLIO.load_owl()` checks cache first, then fetches from GitHub or HTTP
+3. **Parse XML** → `FOLIO.parse_owl()` streams XML parsing with `lxml`, dispatches to specialized parsers
+4. **Parse Classes** → `FOLIO.parse_owl_class()` creates `OWLClass` instances, populates indices
+5. **Parse Properties** → `FOLIO.parse_owl_object_property()` creates `OWLObjectProperty` instances
+6. **Build Graph** → `parse_owl()` constructs class hierarchy edges after all nodes are parsed
+7. **Build Indices** → Populate `iri_to_index`, `label_to_index`, `alt_label_to_index`, trie structure if `marisa_trie` available
+
+**Query Flow:**
+
+1. **Direct Access** → `folio[iri]` or `folio[index]` uses `__getitem__()` with `iri_to_index` for O(1) lookup
+2. **Label Search** → `search_by_label()` uses fuzzy matching via `rapidfuzz`
+3. **Prefix Search** → `search_by_prefix()` uses trie-based prefix matching via `marisa_trie`
+4. **Definition Search** → `search_by_definition()` uses fuzzy matching on definition field
+5. **Semantic Search** → `parallel_search_by_llm()` queries LLM with formatted class batches, reranks results
+6. **Traversal** → `get_subgraph()`, `get_children()`, `get_parents()` traverse class hierarchy via `sub_class_of` and `parent_class_of` fields
+
+**State Management:**
+- Ontology state is immutable after `parse_owl()` completes
+- All indices are read-only maps built once at initialization
+- `refresh()` method reinitializes the entire FOLIO instance to reload ontology
+- Triples are frozen in `_cached_triples` tuple after parsing
+
+## Key Abstractions
+
+**OWLClass:**
+- Purpose: Represent an OWL class from the FOLIO ontology
+- Examples: `folio/models.py` lines 82-551
+- Pattern: Pydantic BaseModel with semantic metadata fields (labels, definitions, examples, translations)
+- Provides serialization: `to_owl_element()`, `to_owl_xml()`, `to_markdown()`, `to_jsonld()`, `to_json()`
+
+**OWLObjectProperty:**
+- Purpose: Represent an OWL object property (relationships between classes)
+- Examples: `folio/models.py` lines 29-80
+- Pattern: Pydantic BaseModel with domain/range constraints
+- Used by: Property queries and triple generation
+
+**FOLIO Graph Service:**
+- Purpose: Unified access point for ontology querying and traversal
+- Examples: `folio/graph.py` lines 159-2164
+- Pattern: Singleton-like class with static factory methods and instance state
+- Key state: `classes` list, `object_properties` list, index mappings, cached triples
+- Duality: Supports both direct IRI lookups (fast, O(1)) and semantic searches (slower, O(n) or LLM-based)
+
+**Type Categories Enum:**
+- Purpose: Provide a known set of FOLIO ontology categories
+- Examples: `folio/graph.py` lines 48-104
+- Pattern: Python Enum mapping human-readable category names to category IRIs
+- Used by: Helper methods like `get_areas_of_law()`, `get_player_actors()`, etc.
+
+## Entry Points
+
+**Public Package API:**
+- Location: `folio/__init__.py`
+- Exports: `FOLIO`, `FOLIOTypes`, `FOLIO_TYPE_IRIS`, `OWLClass`, `OWLObjectProperty`, `NSMAP`
+- Usage: `from folio import FOLIO; folio = FOLIO()`
+
+**FOLIO Constructor:**
+- Location: `folio/graph.py:167-254`
+- Triggers: Module initialization, instantiation by users
+- Responsibilities: Load ontology from source, parse OWL, initialize indices, optionally set up LLM
+
+**Static Factory Methods:**
+- `FOLIO.load_owl_github()` - Load directly from GitHub repository
+- `FOLIO.load_owl_http()` - Load directly from HTTP URL
+- `FOLIO.list_branches()` - List available branches in GitHub repo
+- Used for: Alternative initialization paths, testing, version selection
+
+## Error Handling
+
+**Strategy:** Exceptions propagate up; logging captures warnings for missing dependencies or network issues
+
+**Patterns:**
+- Dependency checks via `importlib.util.find_spec()`: Optional dependencies like `rapidfuzz`, `marisa_trie`, `alea_llm_client` logged as warnings when unavailable
+- HTTP errors wrapped as `RuntimeError` with context (e.g., "Error loading ontology from {url}")
+- IRI normalization handles legacy URL schemes gracefully with fallback prefixes
+- Missing or invalid classes return `None` instead of raising exceptions
+- XML parsing uses `lxml.etree.XMLParser()` with UTF-8 encoding and strict namespace handling
+
+## Cross-Cutting Concerns
+
+**Logging:**
+- Approach: Per-module loggers via `get_logger(__name__)`
+- Used for: Load/parse timing, cache hits/misses, dependency availability, IRI resolution warnings
+- Level: WARNING by default; DEBUG available for detailed trace information
+
+**Validation:**
+- Approach: Pydantic models enforce field types and defaults
+- `OWLClass.is_valid()` checks if label is present (minimal validation)
+- IRI normalization handles multiple legacy URL schemes
+
+**Authentication:**
+- Approach: None required; uses public GitHub API and public HTTP URLs
+- GitHub API calls use basic Accept headers without auth tokens (subject to rate limits)
+- Can be extended via custom LLM providers through `alea_llm_client`
+
+**Caching:**
+- Approach: File-based cache under `~/.folio/cache/{source_type}/{blake2b_hash}.owl`
+- Hash keys based on source parameters: GitHub repo/branch, HTTP URL
+- Transparent to user via `use_cache` flag in constructor
+- No TTL or invalidation beyond manual deletion
+
+**Search Indices:**
+- Approach: Multiple indices for different query types
+- `iri_to_index`: Direct IRI → class position
+- `label_to_index`: Exact label matches → list of indices (handles synonyms)
+- `alt_label_to_index`: Alternative label matches → list of indices
+- `_label_trie`: Prefix matching via `marisa_trie` (only if library available)
+- Triple index: Cached tuple of (subject, predicate, object) triples for semantic queries
+
+---
+
+*Architecture analysis: 2026-04-07*
diff --git a/.planning/codebase/CONCERNS.md b/.planning/codebase/CONCERNS.md
new file mode 100644
index 0000000..87bae03
--- /dev/null
+++ b/.planning/codebase/CONCERNS.md
@@ -0,0 +1,217 @@
+# Codebase Concerns
+
+**Analysis Date:** 2026-04-07
+
+## Tech Debt
+
+**Unparsed RDF/OWL Elements:**
+- Issue: Four OWL element types are recognized but not parsed: DatatypeProperty, AnnotationProperty, NamedIndividual, and RDF Description
+- Files: `folio/graph.py:946-957`
+- Impact: Ontology data in these formats is silently skipped. If FOLIO extends to use these constructs, information loss will occur silently.
+- Fix approach: Implement parsing for each element type with corresponding model classes and storage structures. Add test cases for each type.
+
+**JSON-LD Translation Bug (Destructive Loop):**
+- Issue: In `to_jsonld()` method, translations loop overwrites `skos:altLabel` array on each iteration instead of appending
+- Files: `folio/models.py:465-470`
+- Impact: Only the last translation is preserved in JSON-LD output; earlier translations are lost. This corrupts the output for multilingual classes.
+- Fix approach: Change line 467 from assignment to append check. Initialize the array once outside the loop if not present.
+
+**Incomplete LLM System Prompt:**
+- Issue: LLM search uses a hardcoded minimal system prompt without full task definition
+- Files: `folio/graph.py:1560-1561`
+- Impact: LLM search quality is constrained by insufficient context. Response format may be unpredictable without schema enforcement.
+- Fix approach: Expand system prompt to include task context, output format requirements, and confidence scoring guidelines. Implement token caching once alea-llm-client supports it (noted in TODO at line 8).
+
+**Version Mismatch:**
+- Issue: Package version in `__init__.py` is "0.2.0" but `pyproject.toml` declares "0.2.1"
+- Files: `folio/__init__.py:8`, `pyproject.toml:3`
+- Impact: Metadata and programmatic version checks may be inconsistent with published version. Release tooling may fail or users get wrong version info.
+- Fix approach: Sync both files to the same version. Use single source of truth (consider `pyproject.toml`) and read version dynamically in `__init__.py`.
+
+**Overly Broad Exception Handling:**
+- Issue: LLM initialization catches `Exception` without specificity; logs warning but doesn't re-raise
+- Files: `folio/graph.py:251`
+- Impact: Real errors (API keys missing, network issues) are silently suppressed with warnings. Users don't know LLM search is broken until they call it.
+- Fix approach: Catch specific exceptions (`APIConnectionError`, `AuthenticationError`, etc.). Optionally re-raise with context, or make LLM optional in constructor with explicit flag.
+
+## Known Bugs
+
+**Deduplication During Alternative Label Collection:**
+- Bug: Alternative labels are added without checking if `lang`-tagged and base versions conflict during XML parsing
+- Symptoms: When `xml:lang` altLabels and plain altLabels coexist for the same value, deduplication may fail to catch duplicates
+- Files: `folio/graph.py:657-667`
+- Trigger: Ontology with altLabels like `Name` and `Name` on same class
+- Workaround: None; currently requires manual cleanup after parsing
+
+**IRI Normalization Not Idempotent for Legacy Formats:**
+- Bug: Multiple legacy URL formats map to same IRI, but normalization can fail for mixed formats
+- Symptoms: IRI lookups fail for some legacy URL variations
+- Files: `folio/graph.py:1105-1132`
+- Trigger: Using legacy `soli:`, `lmss:` prefixes with mixed casing or non-standard formatting
+- Workaround: Use normalized FOLIO IRIs when possible
+
+## Security Considerations
+
+**Unvalidated External Network Requests:**
+- Risk: Network requests to GitHub and HTTP endpoints lack timeout enforcement and retry limits
+- Files: `folio/graph.py:279-288`, `folio/graph.py:418-432`, `folio/graph.py:445-456`
+- Current mitigation: `httpx` client used with `raise_for_status()` for HTTP errors
+- Recommendations:
+ - Add explicit timeout parameter to all `httpx.Client()` calls (e.g., `timeout=30`)
+ - Implement exponential backoff retry logic for transient failures
+ - Add rate-limit detection and backoff
+ - Validate URLs before use to prevent SSRF attacks
+
+**Optional Dependency Conditional Logic:**
+- Risk: Search functionality silently degrades if `rapidfuzz`, `marisa_trie`, or `alea_llm_client` are missing; no runtime error until used
+- Files: `folio/graph.py:131-156`
+- Current mitigation: Warnings logged if dependencies not found; methods check if modules are None
+- Recommendations:
+ - Raise `ImportError` in methods that require dependencies if they're not available (fail fast)
+ - Consider making search a separate optional module rather than conditional imports in core module
+ - Document required versions and compatibility in README
+
+**No Input Validation on IRIs:**
+- Risk: User-supplied IRIs passed to search, retrieval, and filtering functions are not validated for format or length
+- Files: `folio/graph.py:1146-1167`, `folio/graph.py:1169-1189`
+- Current mitigation: Normalization and dictionary lookup (fails gracefully with None return)
+- Recommendations:
+ - Add URI format validation using `urllib.parse`
+ - Set max length limits on IRI strings
+ - Add fuzzy matching to suggest similar IRIs on lookup failure
+
+## Performance Bottlenecks
+
+**Linear Search in Triples Filtering:**
+- Problem: Triple filtering operations iterate entire triple list on every call
+- Files: `folio/graph.py:1999-2018`, `folio/graph.py:2020-2056`
+- Cause: Triples stored as list, no indexes on predicate/subject/object fields
+- Improvement path: Build three separate indices (one per field) during parsing. Update `_filter_triples()` to use indexed lookup. Trade memory for O(1) lookup instead of O(n) scan.
+
+**Cache Invalidation on Refresh:**
+- Problem: Calling `refresh()` clears `_cached_triples` but doesn't clear `functools.cache` decorators on methods
+- Files: `folio/graph.py:1260-1266`
+- Cause: `@cache` decorator (lines 525, 1094, 1336, 1990) persists across refresh; old data may be returned
+- Improvement path: Implement cache-clearing method that invalidates all cached methods when data changes. Use decorator wrapper that checks dirty flag.
+
+**JSON-LD Serialization Allocates New Arrays Repeatedly:**
+- Problem: `to_jsonld()` creates new list objects for every field, even empty ones
+- Files: `folio/models.py:406-527`
+- Cause: Pattern of `jsonld_data["field"] = []` on every conditional check
+- Improvement path: Only allocate arrays when content exists. Pre-check item count before initializing.
+
+**Large Trie Object Held in Memory:**
+- Problem: If `marisa_trie` is initialized, trie object persists for entire program lifecycle
+- Files: `folio/graph.py:160-230` (not shown, but initialization pattern)
+- Cause: Trie built during `__init__` with full index
+- Improvement path: Lazy-load trie on first search. Consider memory-mapped disk-based trie for very large ontologies.
+
+## Fragile Areas
+
+**OWL Parsing with Complex Restrictions:**
+- Files: `folio/graph.py:580-618`
+- Why fragile: Complex OWL restrictions (someValuesFrom, allValuesFrom, oneOf) require nested element traversal. Changes to XML structure or namespace handling break silently.
+- Safe modification: Add unit tests for each restriction type. Use XPath selectors instead of manual traversal. Validate namespace mappings before parsing.
+- Test coverage: No specific restriction-type test cases found in test file
+
+**Alternative Label Handling (Multilingual Support):**
+- Files: `folio/graph.py:657-667`, `folio/models.py:462-470`
+- Why fragile: Logic to separate translations from altLabels relies on `xml:lang` attribute presence. Hidden labels are also added to altLabels. Order of operations matters.
+- Safe modification: Separate translations fully into own collection. Dedup hidden labels against altLabels before adding. Document the behavior.
+- Test coverage: Basic multilingual tests exist but no edge case coverage (duplicate translations, missing lang attribute)
+
+**IRI Normalization with Legacy Prefixes:**
+- Files: `folio/graph.py:1100-1132`
+- Why fragile: Multiple legacy URL schemes (soli, lmss) hardcoded. Adding new scheme requires code change. Order of checks matters.
+- Safe modification: Use regex pattern matching instead of sequential `startswith` checks. Consider building prefix map from config.
+- Test coverage: Test exists for one branch; need comprehensive test for all legacy formats and edge cases
+
+## Scaling Limits
+
+**Triple Storage Unbounded in Memory:**
+- Current capacity: Handles FOLIO 2.0.0 (several thousand classes) with <100MB footprint for triples
+- Limit: With very large ontologies (100k+ classes), triple list becomes unbounded linear growth
+- Scaling path: Implement triple store interface that can switch between in-memory list and disk-backed SQLite. Lazy-load triples on demand.
+
+**LLM Context Window Usage:**
+- Current capacity: Minimal system prompt + schema fits in token limit
+- Limit: Once caching and expanded context are added (TODO at line 8), token usage may exceed limits for large searches
+- Scaling path: Implement token counting before LLM calls. Use sliding window context if needed. Cache system prompt tokens once alea-llm-client supports it.
+
+**Search Index Build Time:**
+- Current capacity: Marisa trie builds in <5 seconds for FOLIO 2.0.0
+- Limit: Very large ontologies (1M+ terms) will exceed reasonable build time during initialization
+- Scaling path: Lazy-build search index on first use. Consider pre-built index files. Implement incremental index updates.
+
+## Dependencies at Risk
+
+**alea-llm-client Version Constraint:**
+- Risk: Pinned to `>=0.1.1` with no upper bound until dev dependency. Upstream breaking changes will break search
+- Files: `pyproject.toml:44`, `pyproject.toml:72`
+- Impact: Search API changes in alea-llm-client will require code updates. Cannot use versions with token caching (planned feature).
+- Migration plan: Add upper bound constraint once major version is released. Keep fork or wrapper of LLM calls to ease future migrations.
+
+**lxml Library:**
+- Risk: `lxml>=5.2.2` depends on C bindings; installation can fail on systems without build tools
+- Files: `pyproject.toml:36`
+- Impact: Installation failures on CI systems or containerized environments without C compiler
+- Migration plan: Document build requirements. Consider pure-Python XML parser alternative (xml.etree, but slower). Add CI test on minimal image.
+
+**marisa-trie (Optional Dependency):**
+- Risk: Specialized library with limited maintenance; may not update for new Python versions
+- Files: `pyproject.toml:43`, `pyproject.toml:70`
+- Impact: Search degrades to linear search if marisa-trie not installable. No warnings until user calls search.
+- Migration plan: Implement fallback pure-Python prefix tree. Consider replacing with standard library collections.defaultdict structure.
+
+## Missing Critical Features
+
+**No Ontology Validation:**
+- Problem: Loaded OWL is not validated against FOLIO schema. Invalid or malformed data passes through silently.
+- Blocks: Cannot guarantee data quality in downstream applications. Silent data loss possible (e.g., unimplemented element types).
+- Recommendation: Add schema validator that checks for required fields, valid IRIs, and consistency constraints.
+
+**No Concurrency Support in Mutable State:**
+- Problem: FOLIO class is not thread-safe. Multiple threads accessing ontology simultaneously will cause data races.
+- Blocks: Cannot use FOLIO in concurrent server applications without locks.
+- Recommendation: Make FOLIO immutable after initialization, or add thread-safe wrapper class.
+
+**No Change Notifications:**
+- Problem: When `refresh()` is called, downstream code doesn't know ontology changed.
+- Blocks: Caches at application level won't invalidate. Search results become stale.
+- Recommendation: Implement observer pattern or callback mechanism for refresh events.
+
+## Test Coverage Gaps
+
+**LLM Search Methods Not Tested:**
+- What's not tested: `search_by_llm()`, `parallel_search_by_llm()` methods with actual LLM responses
+- Files: `folio/graph.py:1520-1660`
+- Risk: LLM integration regressions won't be caught. Response parsing edge cases unknown.
+- Priority: **High** - LLM is core feature advertised in documentation
+
+**Complex OWL Constructs:**
+- What's not tested: DatatypeProperty, AnnotationProperty, NamedIndividual, restriction types
+- Files: `folio/graph.py:946-957`
+- Risk: If FOLIO schema adds these elements, silent data loss won't be detected.
+- Priority: **Medium** - Low current impact but future-proofing critical
+
+**Error Cases in Network Loading:**
+- What's not tested: Timeout handling, partial downloads, corrupted response bodies, rate limiting
+- Files: `folio/graph.py:277-457`
+- Risk: Applications fail ungracefully under poor network conditions.
+- Priority: **Medium** - Important for reliability
+
+**Multilingual Translations Edge Cases:**
+- What's not tested: Duplicate translations, missing lang attribute, translation with same value as altLabel
+- Files: `folio/graph.py:657-667`, `folio/models.py:462-470`
+- Risk: Data loss in to_jsonld() when translations present.
+- Priority: **High** - Known data loss bug
+
+**Alternative Label Deduplication:**
+- What's not tested: Deduplication when lang-tagged and base versions of same label coexist
+- Files: `folio/graph.py:657-667`
+- Risk: Duplicate labels in search results; inflated result counts.
+- Priority: **Medium** - Recent fix but edge cases unknown
+
+---
+
+*Concerns audit: 2026-04-07*
diff --git a/.planning/codebase/CONVENTIONS.md b/.planning/codebase/CONVENTIONS.md
new file mode 100644
index 0000000..9ff645d
--- /dev/null
+++ b/.planning/codebase/CONVENTIONS.md
@@ -0,0 +1,374 @@
+# Coding Conventions
+
+**Analysis Date:** 2026-04-07
+
+## Naming Patterns
+
+**Files:**
+- Module files use lowercase with underscores: `graph.py`, `models.py`, `logger.py`, `config.py`
+- Example files use lowercase with underscores describing functionality: `basic_taxonomy.py`, `initialize_client.py`, `property_categories.py`
+
+**Classes:**
+- Use PascalCase: `FOLIO`, `OWLClass`, `OWLObjectProperty`, `FOLIOConfiguration`, `FOLIOTypes`
+- Enum members use UPPER_CASE_WITH_UNDERSCORES: `ACTOR_PLAYER`, `AREA_OF_LAW`, `ASSET_TYPE`
+
+**Functions and Methods:**
+- Use snake_case: `get_logger()`, `load_owl_github()`, `search_by_label()`, `to_markdown()`, `is_valid()`
+- Conversion methods use `to_*()` pattern: `to_owl_element()`, `to_owl_xml()`, `to_json()`, `to_jsonld()`, `to_markdown()`
+- Factory methods use `from_*()` pattern: `from_json()`
+- Getter methods use `get_*()` pattern: `get_logger()`, `get_types()`, `get_property()`, `get_triples_by_predicate()`
+- Filter/search methods use `search_*()` pattern: `search_by_prefix()`, `search_by_label()`, `search_by_definition()`
+
+**Variables and Attributes:**
+- Use snake_case for attributes and local variables: `source_type`, `http_url`, `github_repo_owner`, `cache_path`, `iri_to_index`
+- Dictionary keys use lowercase with underscores: `"folio"`, `"repo_owner"`, `"use_cache"`
+- Private/internal attributes do not use underscore prefix in Pydantic models (Field definitions)
+
+**Type Hints:**
+- Always use type hints for function parameters and return types: `def get_logger(name: str) -> logging.Logger:`
+- Use Python 3.10+ union syntax with `|` where appropriate: `str | Path`, `Optional[str]`, `Dict[str, int]`
+- Use forward references for self-referencing types: `from __future__ import annotations`
+- Generic types use fully qualified names: `Dict`, `List`, `Optional`, `Tuple`, `Literal`
+
+## Code Style
+
+**Formatting:**
+- Line length: 120 characters max (configured in `pyproject.toml`)
+- Formatter: `black` and `ruff` (via pre-commit hooks)
+- Indentation: 4 spaces
+
+**Linting:**
+- Primary linter: `pylint` configured in `pyproject.toml`
+- Pre-commit hooks: `ruff` (check --fix), `ruff-format`, `pre-commit-hooks`
+- pylint disabled rules: `line-too-long`, `too-few-public-methods`, `no-self-argument`, `cyclic-import`
+- File-level pylint directives used: `# pylint: disable=fixme,no-member,unsupported-assignment-operation,too-many-lines,too-many-public-methods,invalid-name`
+
+## Import Organization
+
+**Order:**
+1. Standard library imports (`sys`, `asyncio`, `json`, `logging`, `pathlib`, etc.)
+2. Third-party imports (`pydantic`, `lxml`, `httpx`, etc.)
+3. Project imports (`from folio import...`, `from folio.logger import...`)
+
+**Example from `folio/graph.py`:**
+```python
+# future import for self-referencing type hints
+from __future__ import annotations
+
+# imports
+import asyncio
+import base64
+import hashlib
+import importlib.util
+import json
+import time
+import traceback
+import uuid
+from enum import Enum
+from functools import cache
+from pathlib import Path
+from typing import Dict, List, Literal, Optional, Tuple
+
+# packages
+import httpx
+import lxml.etree
+from alea_llm_client import BaseAIModel
+
+# project imports
+from folio.config import (...)
+from folio.logger import get_logger
+from folio.models import OWLClass, OWLObjectProperty, NSMAP
+```
+
+**Path Aliases:**
+- Not used; imports are explicit with relative module names
+- Configuration imports from `folio.config`, logging from `folio.logger`, models from `folio.models`
+
+## Docstrings
+
+**Format:** Google-style docstrings for all public classes and methods
+
+**Class docstrings:**
+```python
+class OWLClass(BaseModel):
+ """
+ OWLClass model for the FOLIO package, which represents an OWL class in the FOLIO
+ ontology/taxonomy style.
+
+ TODO: think about future-proofing for next-gen roadmap.
+ """
+```
+
+**Method docstrings:**
+```python
+def is_valid(self) -> bool:
+ """
+ Check if the OWL class is valid.
+
+ Returns:
+ bool: True if the OWL class is valid, False otherwise.
+ """
+ return self.label is not None
+```
+
+**Function docstrings with arguments:**
+```python
+@staticmethod
+def load_owl(
+ source_type: str = DEFAULT_SOURCE_TYPE,
+ http_url: Optional[str] = DEFAULT_HTTP_URL,
+ github_repo_owner: str = DEFAULT_GITHUB_REPO_OWNER,
+ github_repo_name: str = DEFAULT_GITHUB_REPO_NAME,
+ github_repo_branch: str = DEFAULT_GITHUB_REPO_BRANCH,
+ use_cache: bool = True,
+) -> str:
+ """
+ Load the FOLIO ontology in OWL format.
+
+ Args:
+ source_type (str): The source type for loading the ontology. Either "github" or "http".
+ http_url (Optional[str]): The HTTP URL for the ontology.
+ github_repo_owner (str): The owner of the GitHub repository.
+ github_repo_name (str): The name of the GitHub repository.
+ github_repo_branch (str): The branch of the GitHub repository.
+ use_cache (bool): Whether to use the local cache.
+ """
+```
+
+## Comments
+
+**When to Comment:**
+- Explain "why" not "what" — code that is self-documenting via clear naming does not need comments
+- Use comments for complex logic, non-obvious decisions, or important caveats
+- Include comments for workarounds or temporary solutions
+
+**Example from `folio/models.py`:**
+```python
+# We no longer need to handle seeAlso restrictions separately since all seeAlso
+# relationships are now in the main see_also list
+
+# add the label element
+label_element = lxml.etree.Element(f"{{{NSMAP['rdfs']}}}label", nsmap=NSMAP)
+```
+
+**TODO/FIXME markers:**
+- Used to mark incomplete work: `TODO: think about future-proofing for next-gen roadmap.`
+- Used to mark needed implementations: `TODO: implement token caching layer in system prompt for search`
+- Flagged by pylint with `fixme` disabled to allow checking
+
+## Module Constants
+
+**Configuration constants:** Defined at module level in `config.py` with `DEFAULT_` prefix
+```python
+DEFAULT_CACHE_DIR: Path = Path.home() / ".folio" / "cache"
+DEFAULT_MAX_DEPTH: int = 16
+MAX_IRI_ATTEMPTS: int = 16
+DEFAULT_MAX_TOKENS: int = 1024
+```
+
+**Module-level dictionaries:** Use UPPER_CASE for enums and mappings
+```python
+FOLIO_TYPE_IRIS = {
+ FOLIOTypes.ACTOR_PLAYER: "R8CdMpOM0RmyrgCCvbpiLS0",
+ FOLIOTypes.AREA_OF_LAW: "RSYBzf149Mi5KE0YtmpUmr",
+ ...
+}
+
+NSMAP = {
+ None: "https://folio.openlegalstandard.org/",
+ "dc": "http://purl.org/dc/elements/1.1/",
+ ...
+}
+```
+
+## Data Validation
+
+**Framework:** Pydantic v2 for all data models
+
+**Usage:** `BaseModel` for structured data with Field descriptors for documentation
+```python
+class OWLClass(BaseModel):
+ iri: str = Field(..., description="{http://www.w3.org/2002/07/owl#}Class")
+ label: Optional[str] = Field(
+ None, description="{http://www.w3.org/2000/01/rdf-schema#}label"
+ )
+ sub_class_of: List[str] = Field(
+ default_factory=list,
+ description="{http://www.w3.org/2000/01/rdf-schema#}subClassOf",
+ )
+```
+
+**Validation methods:** Use `model_validate()` and `model_validate_json()` from Pydantic
+```python
+@classmethod
+def from_json(cls, json_string: str) -> "OWLClass":
+ return cls.model_validate_json(json_string)
+```
+
+## Error Handling
+
+**Pattern:** Raise specific exception types with context-rich messages
+
+**For external API errors:**
+```python
+try:
+ with httpx.Client() as client:
+ response = client.get(url, headers=headers)
+ response.raise_for_status()
+ branches = response.json()
+ return [branch["name"] for branch in branches]
+except httpx.HTTPStatusError as e:
+ raise RuntimeError(
+ f"Error listing branches for {repo_owner}/{repo_name}"
+ ) from e
+```
+
+**For validation errors:**
+```python
+if source_type == "github":
+ cache_key = f"{github_repo_owner}/{github_repo_name}/{github_repo_branch}"
+elif source_type == "http":
+ if http_url is None:
+ raise ValueError("HTTP URL must be provided for source type 'http'.")
+ cache_key = http_url
+else:
+ raise ValueError("Invalid source type. Must be either 'github' or 'http'.")
+```
+
+**For import errors:** Graceful handling with logging warnings
+```python
+try:
+ if importlib.util.find_spec("rapidfuzz") is not None:
+ import rapidfuzz
+ else:
+ LOGGER.warning("Disabling search functionality: rapidfuzz not found.")
+ rapidfuzz = None
+except ImportError as e:
+ LOGGER.warning("Failed to check for search functionality: %s", e)
+ rapidfuzz = None
+```
+
+**For broad exception handling:** Only when appropriate, marked with `# pylint: disable=broad-except`
+```python
+try:
+ if llm is None:
+ self.llm = alea_llm_client.OpenAIModel(model="gpt-4o")
+ else:
+ self.llm = llm
+ LOGGER.info("Initialized LLM model: %s", self.llm)
+except Exception: # pylint: disable=broad-except
+ LOGGER.warning(
+ "Failed to initialize LLM model: %s", traceback.format_exc()
+ )
+```
+
+## Logging
+
+**Framework:** Standard library `logging` module via `get_logger()` utility
+
+**Usage:** `LOGGER = get_logger(__name__)` at module level in `folio/logger.py`
+
+**Log levels:**
+- `LOGGER.warning()` for optional features that could not be enabled or recoverable issues
+- `LOGGER.info()` for significant operations (loading ontology, parsing, initialization)
+- Default level: WARNING (set in `folio/logger.py`)
+
+**Patterns:**
+```python
+LOGGER.info("Loading FOLIO ontology from %s...", source_type)
+LOGGER.info("Parsed FOLIO ontology in %.2f seconds", end_time - start_time)
+LOGGER.warning("Disabling search functionality: rapidfuzz not found.")
+```
+
+## Function Design
+
+**Size:** Methods can be longer (50-200 lines) when parsing complex XML or building data structures
+
+**Parameters:**
+- Use keyword arguments for better readability with multiple parameters
+- Provide reasonable defaults for optional parameters: `use_cache: bool = True`
+- Use static methods for utility functions not requiring instance state: `@staticmethod def list_branches(...)`
+
+**Return Values:**
+- Always include return type hint
+- Return `None` explicitly when appropriate: `-> None`
+- Return typed collections: `-> List[str]`, `-> Dict[str, int]`, `-> Optional[str]`
+- Methods that return another class instance use the class name in quotes for forward references
+
+**Example from `folio/graph.py`:**
+```python
+@staticmethod
+def load_owl_github(
+ repo_owner: str = DEFAULT_GITHUB_REPO_OWNER,
+ repo_name: str = DEFAULT_GITHUB_REPO_NAME,
+ repo_branch: str = DEFAULT_GITHUB_REPO_BRANCH,
+) -> str:
+ """Load the FOLIO ontology in OWL format from a GitHub repository."""
+ # GitHub URL for the ontology file
+ url = f"{DEFAULT_GITHUB_OBJECT_URL}/{repo_owner}/{repo_name}/{repo_branch}/FOLIO.owl"
+ try:
+ with httpx.Client() as client:
+ LOGGER.info(
+ "Loading ontology from %s/%s/%s", repo_owner, repo_name, repo_branch
+ )
+ response = client.get(url)
+ response.raise_for_status()
+ return response.text
+ except httpx.HTTPStatusError as e:
+ raise RuntimeError(...) from e
+```
+
+## Module Design
+
+**Exports:** Explicit `__all__` in `folio/__init__.py` for public API
+```python
+__all__ = [
+ "FOLIO",
+ "FOLIOTypes",
+ "FOLIO_TYPE_IRIS",
+ "OWLClass",
+ "OWLObjectProperty",
+ "NSMAP",
+]
+```
+
+**Barrel Files:** Not used; imports are from specific modules
+
+**Module organization:**
+- `folio/__init__.py` — Package exports and version metadata
+- `folio/graph.py` — Main FOLIO class and FOLIOTypes enum
+- `folio/models.py` — OWLClass, OWLObjectProperty, NSMAP definitions
+- `folio/config.py` — Configuration management and defaults
+- `folio/logger.py` — Logging utility
+
+## Class Design
+
+**BaseModel usage:** All data structures inherit from Pydantic `BaseModel`
+- Provides validation, serialization (`model_dump()`, `model_dump_json()`)
+- Field descriptors document each attribute with SKOS/RDF semantics
+
+**Instance attributes initialized in `__init__`:**
+```python
+self.source_type: str = source_type
+self.http_url: Optional[str] = http_url
+self.tree: Optional[lxml.etree._Element] = None
+self.classes: List[OWLClass] = []
+self.iri_to_index: Dict[str, int] = {}
+```
+
+**Lazy initialization of optional features:**
+```python
+self.llm: Optional[BaseAIModel] = None
+if alea_llm_client is not None:
+ try:
+ if llm is None:
+ self.llm = alea_llm_client.OpenAIModel(model="gpt-4o")
+ else:
+ self.llm = llm
+ except Exception:
+ LOGGER.warning(...)
+```
+
+---
+
+*Convention analysis: 2026-04-07*
diff --git a/.planning/codebase/INTEGRATIONS.md b/.planning/codebase/INTEGRATIONS.md
new file mode 100644
index 0000000..9562f45
--- /dev/null
+++ b/.planning/codebase/INTEGRATIONS.md
@@ -0,0 +1,159 @@
+# External Integrations
+
+**Analysis Date:** 2026-04-07
+
+## APIs & External Services
+
+**GitHub API:**
+- GitHub Repositories - Fetch FOLIO ontology metadata and raw ontology files
+ - SDK/Client: httpx (HTTP client)
+ - Endpoint: `https://api.github.com/repos/{repo_owner}/{repo_name}/branches` (list branches)
+ - Implementation: `folio/graph.py` lines 257–292 (`FOLIO.list_branches()`)
+ - Authentication: Optional GitHub token via headers (not currently enforced)
+ - Default repo: `alea-institute/FOLIO` branch `2.0.0`
+
+**GitHub Objects (Raw Content):**
+- GitHub Raw File CDN - Stream ontology OWL XML files
+ - SDK/Client: httpx (HTTP client with redirect following)
+ - Endpoint: `https://raw.githubusercontent.com/{repo_owner}/{repo_name}/{branch}/FOLIO.owl`
+ - Implementation: `folio/graph.py` lines 401–434 (`FOLIO.load_owl_github()`)
+ - Authentication: None required for public repos
+ - Caching: Local cache at `~/.folio/cache/` to reduce API calls
+
+**HTTP/Generic URLs:**
+- Remote ontology servers - Load FOLIO.owl from any HTTP endpoint
+ - SDK/Client: httpx (HTTP client with redirect following)
+ - Endpoint: User-provided via `http_url` parameter or config
+ - Implementation: `folio/graph.py` lines 437–457 (`FOLIO.load_owl_http()`)
+ - Authentication: None built-in; user responsible for including auth in URL
+ - Default: None (GitHub is preferred)
+
+**OpenAI API (via alea-llm-client):**
+- GPT-4o model for semantic label search
+ - SDK/Client: alea-llm-client 0.1.1+ (wraps OpenAI SDK)
+ - Model: `gpt-4o` (hardcoded default in `folio/graph.py` line 247)
+ - Authentication: `OPENAI_API_KEY` environment variable (managed by alea-llm-client)
+ - Implementation: `folio/graph.py` lines 244–250 (optional LLM initialization)
+ - Graceful degradation: If `alea_llm_client` not installed or initialization fails, search falls back to rapidfuzz
+ - Used by: Semantic search functionality via `search_with_decoder()` method (not shown in excerpt but referenced in comments)
+
+## Data Storage
+
+**Databases:**
+- None used - Folio is a read-only ontology library
+
+**File Storage:**
+- Local filesystem only for caching
+ - Cache directory: `~/.folio/cache/` (default, configurable via `DEFAULT_CACHE_DIR` in `folio/graph.py` line 110)
+ - Cache structure: `{cache_root}/{source_type}/{hash(cache_key)}.owl`
+ - Hash algorithm: BLAKE2b (256-bit, `folio/graph.py` line 334)
+ - Persistence: Persistent across sessions; users responsible for cleanup
+
+**Caching:**
+- Local filesystem-based caching enabled by default
+ - Implementation: `folio/graph.py` lines 295–398 (`FOLIO.load_cache()` and `FOLIO.save_cache()`)
+ - Cache invalidation: Manual (no TTL); caching can be disabled via `use_cache=False` parameter
+ - Scope: Per ontology source (GitHub repo/branch or HTTP URL)
+
+## Authentication & Identity
+
+**Auth Provider:**
+- None built-in; library is read-only for public ontologies
+- GitHub: No auth required for public `alea-institute/FOLIO` repository (the default)
+- Custom HTTP: Users must include auth in URL if required
+- OpenAI: Delegated to alea-llm-client; expects `OPENAI_API_KEY` environment variable
+
+**Implementation:**
+- GitHub API calls pass minimal headers (`Accept: application/vnd.github.v3+json` in `folio/graph.py` line 275)
+- No API key management in folio codebase
+- All auth is caller's responsibility
+
+## Monitoring & Observability
+
+**Error Tracking:**
+- None configured - Library logs errors but doesn't integrate with external error tracking
+- Local logging via `folio/logger.py` (standard Python logging)
+
+**Logs:**
+- Standard Python logging at module level
+ - Logger initialized: `LOGGER = get_logger(__name__)` in `folio/graph.py` line 128
+ - Log handler configured in `folio/logger.py`
+ - Key log points:
+ - Ontology load start/end with duration (`folio/graph.py` lines 222–233, 236–240)
+ - Cache hits/misses (`folio/graph.py` lines 342, 347)
+ - Search functionality availability (`folio/graph.py` lines 135, 141, 151)
+ - LLM model initialization success/failure (`folio/graph.py` lines 250, 252–254)
+ - GitHub branch listing (`folio/graph.py` line 280)
+
+## CI/CD & Deployment
+
+**Hosting:**
+- GitHub source repository: `https://github.com/alea-institute/folio-python`
+- Documentation: Read the Docs (`.readthedocs.yaml` configured)
+- Package distribution: PyPI (Python Package Index)
+
+**CI Pipeline:**
+- GitHub Actions workflows in `.github/workflows/`
+ - `CI.yml`: Runs on push to main/master/dev/test, PRs, and manual dispatch
+ - Tests on multiple Linux architectures (x86_64, x86, aarch64, armv7, s390x, ppc64le)
+ - Runs pytest suite with coverage reporting
+ - Builds distribution artifacts
+ - `publish.yml`: Triggers on GitHub release (published event)
+ - Builds distribution (wheel and source)
+ - Publishes to PyPI via `pypa/gh-action-pypi-publish@release/v1` (trusted publishing with OIDC)
+ - No manual credentials needed in CI environment
+
+**Build Process:**
+- Build tool: `hatchling` (backend in `pyproject.toml` line 106)
+- Build command: `python -m build` (`.github/workflows/publish.yml` line 22)
+- Artifacts:
+ - Source distribution (sdist): excludes tests, docs, examples, docker
+ - Wheel: Binary distribution, excludes same
+
+**Documentation Build:**
+- Read the Docs configuration: `.readthedocs.yaml` (version 2 format)
+- Python version: 3.11
+- OS: Ubuntu 24.04
+- Build tool: Sphinx
+- Config file: `docs/conf.py`
+- Output formats: HTML, PDF, ePub
+- Requirements: `docs/requirements.txt`
+
+## Environment Configuration
+
+**Required env vars:**
+- `OPENAI_API_KEY` - Only if using LLM semantic search (alea-llm-client requires this)
+- All other configuration via JSON file (`~/.folio/config.json`) or constructor parameters
+
+**Secrets location:**
+- Not stored in repository (GitHub Actions uses trusted publishing, no API tokens in code)
+- `OPENAI_API_KEY` should be set in user environment or GitHub Actions secrets (not configured in visible workflows)
+- Pre-commit hook `gitleaks` (`.pre-commit-config.yaml` line 22) prevents accidental secret commits
+
+**Configuration file structure:**
+```json
+{
+ "folio": {
+ "source": "github",
+ "repo_owner": "alea-institute",
+ "repo_name": "FOLIO",
+ "branch": "2.0.0",
+ "path": "FOLIO.owl",
+ "use_cache": true
+ }
+}
+```
+- Location: `~/.folio/config.json` (home directory, `folio/config.py` line 20)
+- Loaded by: `FOLIOConfiguration.load_config()` in `folio/config.py` lines 87–128
+
+## Webhooks & Callbacks
+
+**Incoming:**
+- None - Library does not provide webhook endpoints
+
+**Outgoing:**
+- None - Library does not send webhooks
+
+---
+
+*Integration audit: 2026-04-07*
diff --git a/.planning/codebase/STACK.md b/.planning/codebase/STACK.md
new file mode 100644
index 0000000..1e66120
--- /dev/null
+++ b/.planning/codebase/STACK.md
@@ -0,0 +1,136 @@
+# Technology Stack
+
+**Analysis Date:** 2026-04-07
+
+## Languages
+
+**Primary:**
+- Python 3.10+ - Full library implementation; supports 3.10, 3.11, 3.12, 3.13
+- XML/OWL - Ontology format (FOLIO.owl files parsed via lxml)
+
+**Configuration:**
+- TOML - Project configuration (`pyproject.toml`)
+- YAML - CI/CD and documentation config
+- JSON - Runtime configuration files
+
+## Runtime
+
+**Environment:**
+- Python 3.10–3.13 (configurable, currently testing on 3.13)
+
+**Package Manager:**
+- UV (fast Python package manager) - Primary
+- pip - Fallback in CI/CD workflows
+- poetry - Used in legacy CI workflow (`.github/workflows/CI.yml` line 56)
+- Lockfile: `uv.lock` present (reproducible builds)
+
+## Frameworks
+
+**Core:**
+- pydantic 2.8.2+ - Data validation and OWL model definitions (`folio/models.py`)
+- lxml 5.2.2+ - XML/OWL ontology parsing (`folio/graph.py`)
+- httpx 0.27.2+ - HTTP client for GitHub API and remote ontology loading (`folio/graph.py` lines 31, 279–281, 420, 447)
+
+**Search (Optional):**
+- rapidfuzz 3.10.0–3.x - Fuzzy string matching for label search (`folio/graph.py` lines 132–134, 1357–1363)
+- marisa-trie 1.2.0–1.x - Trie-based efficient label indexing (`folio/graph.py` lines 138–139, 1005, 1012)
+- alea-llm-client 0.1.1+ - AI model integration for semantic search (`folio/graph.py` lines 144–152, 247)
+
+**Testing:**
+- pytest 8.3.1–8.x - Test runner
+- pytest-asyncio 0.23.8–0.24.x - Async test support
+- pytest-benchmark 4.0.0–4.x - Performance benchmarking
+- pytest-cov 5.0.0–5.x - Code coverage reporting
+
+**Development:**
+- black 24.4.2–24.x - Code formatting
+- pylint 3.2.7–3.x - Linting
+- ruff (v0.6.3) - Fast linting and formatting via pre-commit
+- isort - Import sorting (configured via `pyproject.toml` lines 127–129)
+- types-lxml 2024.8.7–2024.x - Type hints for lxml
+
+**Documentation:**
+- Sphinx 7.4.7–7.x - Documentation generation
+- myst-parser 3.0.1–3.x - Markdown support in Sphinx
+- sphinx-book-theme 1.1.3–1.x - Modern Sphinx theme
+- sphinxcontrib-mermaid 0.9.2–0.10.x - Diagram support
+- sphinx-copybutton 0.5.2–0.6.x - Copy-to-clipboard for code
+- sphinxext-opengraph 0.9.1–0.10.x - Open Graph meta tags
+- sphinx-plausible 0.1.2–0.2.x - Privacy-focused analytics
+
+**Build:**
+- hatchling (build backend in `pyproject.toml` line 106)
+- pip - Build tool wrapper
+
+## Key Dependencies
+
+**Critical:**
+- pydantic - Validates and structures OWL class/property models; required for all parsing
+- lxml - Parses OWL XML ontology files; no fallback
+- httpx - Fetches ontology from GitHub API (`https://api.github.com`) and GitHub Objects (`https://raw.githubusercontent.com`)
+
+**Infrastructure:**
+- alea-llm-client 0.1.3 (in uv.lock) - Wraps OpenAI API for LLM-based semantic search; graceful fallback if not installed (`folio/graph.py` lines 144–152)
+- rapidfuzz - Enables fuzzy label search; degrades gracefully (`folio/graph.py` line 135)
+- marisa-trie - Enables prefix-based label trie search; degrades gracefully (`folio/graph.py` line 141)
+
+## Configuration
+
+**Environment:**
+- Configuration loaded from `~/.folio/config.json` via `FOLIOConfiguration.load_config()` in `folio/config.py` lines 87–128
+- Environment variables: None required; all config via JSON file or constructor parameters
+- GitHub API: Accessed via httpx with default base URL `https://api.github.com` (`folio/config.py` line 23)
+- GitHub Objects: Accessed via `https://raw.githubusercontent.com` for raw file downloads (`folio/config.py` line 24)
+
+**Build:**
+- `pyproject.toml` lines 75–79: UV default dependency groups include `["dev", "search"]`
+- ruff configuration: black profile, 120 character line length (`.pre-commit-config.yaml` line 21)
+- isort configuration: black profile, 120 character line length (`pyproject.toml` lines 127–129)
+
+**Key Configs Required:**
+- Source type: `"github"` (default) or `"http"` (`folio/config.py` lines 46–47)
+- GitHub repo owner: `"alea-institute"` (default, `folio/config.py` line 33)
+- GitHub repo name: `"FOLIO"` (default, `folio/config.py` line 34)
+- GitHub repo branch: `"2.0.0"` (default, `folio/config.py` line 35)
+- HTTP URL: Optional, only for `"http"` source type (`folio/config.py` line 30)
+- Caching: Enabled by default at `~/.folio/cache/` (`folio/graph.py` line 110)
+
+## Platform Requirements
+
+**Development:**
+- Python 3.10+ with pip/UV
+- lxml build dependencies (libxml2, libxslt on Ubuntu: `sudo apt-get install libxml2-dev libxslt1-dev`)
+- Git (for cloning FOLIO ontology from GitHub)
+- Pre-commit hooks configured (ruff, gitleaks security scanner)
+
+**Production:**
+- Python 3.10+
+- Network access to `https://api.github.com` and `https://raw.githubusercontent.com` (if using GitHub source)
+- Local filesystem access for caching (`~/.folio/cache/`)
+- OpenAI API key environment variable if using LLM search (`OPENAI_API_KEY` for alea-llm-client)
+
+**CI/CD Deployment:**
+- GitHub Actions workflow triggers on release (publish.yml) and push/PR to main/dev (CI.yml)
+- PyPI publishing via `pypa/gh-action-pypi-publish@release/v1` (trusted publishing, OIDC)
+- Read the Docs integration: Build configuration in `.readthedocs.yaml` lines 1–32 (Python 3.11, Sphinx)
+- Supported architectures: x86_64, x86, aarch64, armv7, s390x, ppc64le (via maturin in CI.yml)
+
+## Dependency Groups
+
+**[project.optional-dependencies] - search:**
+- rapidfuzz 3.10.0–3.x
+- marisa-trie 1.2.0–1.x
+- alea-llm-client 0.1.1+
+
+**[dependency-groups.dev:**
+- Testing: pytest, pytest-asyncio, pytest-benchmark, pytest-cov
+- Linting: pylint, black (deprecated in favor of ruff)
+- Documentation: Sphinx, myst-parser, sphinx-book-theme, sphinxcontrib-mermaid
+- Type hints: types-lxml
+
+**[dependency-groups.search:**
+- Same as `[project.optional-dependencies.search]` but with explicit versions (rapidfuzz 3.9.7+, alea-llm-client <0.2)
+
+---
+
+*Stack analysis: 2026-04-07*
diff --git a/.planning/codebase/STRUCTURE.md b/.planning/codebase/STRUCTURE.md
new file mode 100644
index 0000000..622a866
--- /dev/null
+++ b/.planning/codebase/STRUCTURE.md
@@ -0,0 +1,212 @@
+# Codebase Structure
+
+**Analysis Date:** 2026-04-07
+
+## Directory Layout
+
+```
+folio-python/
+├── folio/ # Main library package
+│ ├── __init__.py # Public API exports
+│ ├── models.py # Data models (OWLClass, OWLObjectProperty)
+│ ├── graph.py # Core FOLIO ontology service
+│ ├── config.py # Configuration management
+│ └── logger.py # Logging utilities
+├── tests/ # Test suite
+│ └── test_folio.py # Main test file
+├── examples/ # Usage examples
+│ ├── initialize_client.py # Initialization examples
+│ ├── basic_search.py # Search functionality
+│ ├── basic_graph.py # Graph traversal
+│ ├── basic_taxonomy.py # Taxonomy exploration
+│ ├── basic_traversal.py # Parent/child traversal
+│ ├── basic_triples.py # Triple queries
+│ ├── basic_object_properties.py # Object property queries
+│ ├── semantic_connections.py # Semantic relationship finding
+│ ├── property_categories.py # Property usage analysis
+│ ├── property_frequency.py # Property frequency analysis
+│ └── llm_search.py # LLM-based semantic search
+├── docs/ # Sphinx documentation
+│ ├── conf.py # Sphinx configuration
+│ ├── index.md # Documentation index
+│ ├── examples.md # Example documentation
+│ └── folio/ # Auto-generated module docs
+├── docker/ # Docker build files
+├── .github/ # GitHub workflows (CI/CD)
+├── .planning/ # GSD planning documents
+├── pyproject.toml # Project metadata and dependencies
+├── README.md # Main documentation
+├── CHANGES.md # Changelog
+├── CONTRIBUTING.md # Contributing guidelines
+└── LICENSE # MIT license
+```
+
+## Directory Purposes
+
+**folio/:**
+- Purpose: Main library package with all source code
+- Contains: Core modules for ontology loading, parsing, querying, and data models
+- Key files: `graph.py` (largest, ~2164 lines), `models.py` (~552 lines)
+
+**tests/:**
+- Purpose: Test suite for library functionality
+- Contains: Single `test_folio.py` file with pytest test cases
+- Tests coverage: Initialization, loading, parsing, searching, graph traversal
+
+**examples/:**
+- Purpose: Executable usage examples demonstrating library features
+- Contains: 11 Python scripts showing initialization, search, traversal, properties, and LLM integration
+- Not included in distribution (per `pyproject.toml` excludes)
+
+**docs/:**
+- Purpose: Sphinx documentation source
+- Contains: Configuration, index, examples guide, and auto-generated API docs
+- Build target: Generates HTML documentation (hosted on ReadTheDocs)
+
+**docker/:**
+- Purpose: Docker containerization for documentation/development
+- Contains: Dockerfile and related build files
+
+**.github/:**
+- Purpose: GitHub Actions CI/CD workflows
+- Contains: Automated testing, linting, and publishing pipelines
+
+**.planning/:**
+- Purpose: GSD methodology planning documents
+- Contains: Architecture, structure, testing, conventions, concerns analysis
+
+## Key File Locations
+
+**Entry Points:**
+- `folio/__init__.py`: Package initialization, public API exports (lines 1-28)
+- `folio/graph.py:167-254`: `FOLIO.__init__()` constructor, the main entry point for users
+
+**Configuration:**
+- `folio/config.py`: `FOLIOConfiguration` model, default constants, cache path definitions
+- `pyproject.toml`: Project metadata, dependencies, tool configurations
+- `config.json`: Example configuration file for users (minimal, shows structure)
+
+**Core Logic:**
+- `folio/graph.py:544-775`: `parse_owl_class()` - OWL class parsing logic
+- `folio/graph.py:775-904`: `parse_owl_object_property()` - Property parsing logic
+- `folio/graph.py:961-1012`: `parse_owl()` - Main parsing orchestrator, index building
+- `folio/graph.py:1014-1043`: `get_subgraph()` - Recursive graph traversal
+- `folio/graph.py:1146-1167`: `__getitem__()` - Direct IRI/index access
+- `folio/graph.py:1289-1336`: `search_by_prefix()` - Trie-based prefix search
+- `folio/graph.py:1370-1417`: `search_by_label()` - Fuzzy label search
+- `folio/graph.py:2058-2137`: `find_connections()` - Semantic relationship queries
+
+**Testing:**
+- `tests/test_folio.py`: All test cases (~400+ lines)
+- Pytest configuration in `pyproject.toml:131-132`
+
+**Data Models:**
+- `folio/models.py:15-26`: NSMAP namespace definitions
+- `folio/models.py:29-80`: `OWLObjectProperty` class
+- `folio/models.py:82-551`: `OWLClass` class with serialization methods
+
+**Utilities:**
+- `folio/logger.py`: `get_logger()` function for module-level logging
+- `folio/graph.py:255-435`: Static methods for loading ontology from GitHub/HTTP
+
+## Naming Conventions
+
+**Files:**
+- Source files: `lowercase_with_underscores.py` (e.g., `graph.py`, `config.py`)
+- Example files: `lowercase_with_underscores.py` (e.g., `basic_search.py`, `llm_search.py`)
+- Test files: `test_*.py` following pytest convention
+
+**Classes:**
+- Domain models: PascalCase (e.g., `OWLClass`, `OWLObjectProperty`)
+- Configuration: PascalCase (e.g., `FOLIOConfiguration`)
+- Enums: PascalCase (e.g., `FOLIOTypes`)
+
+**Functions:**
+- Methods and functions: snake_case (e.g., `parse_owl_class`, `search_by_label`, `get_subgraph`)
+- Dunder methods: `__method_name__()` (e.g., `__init__`, `__getitem__`, `__contains__`)
+- Static methods: snake_case with `@staticmethod` decorator
+
+**Variables:**
+- Module-level constants: UPPERCASE_WITH_UNDERSCORES (e.g., `DEFAULT_CACHE_DIR`, `OWL_THING`, `MIN_PREFIX_LENGTH`)
+- Instance variables: snake_case (e.g., `self.classes`, `self.iri_to_index`, `self.label_trie`)
+- Function parameters: snake_case (e.g., `source_type`, `max_depth`, `github_repo_owner`)
+
+**Directories:**
+- Package directories: lowercase (e.g., `folio/`)
+- Documentation: `docs/`
+- Tests: `tests/`
+- Examples: `examples/`
+- Docker: `docker/`
+
+## Where to Add New Code
+
+**New Feature / Search Method:**
+- Primary code: `folio/graph.py` in the `FOLIO` class
+- Pattern: Add method with signature following existing methods (e.g., `search_by_*`, `get_*`)
+- Use `self.classes` list and existing indices for queries
+- Populate indices if adding new search capability
+- Tests: Add test case in `tests/test_folio.py`
+
+**New Data Model / Serialization Format:**
+- Implementation: Add method to `OWLClass` or `OWLObjectProperty` in `folio/models.py`
+- Pattern: Follow `to_owl_xml()`, `to_markdown()`, `to_jsonld()` pattern
+- Use `NSMAP` for namespace handling
+- Tests: Add test in `tests/test_folio.py`
+
+**New Query Type / Graph Operation:**
+- Implementation: `folio/graph.py` in the `FOLIO` class
+- Pattern: Leverage existing `get_subgraph()`, `get_children()`, `get_parents()` for traversal
+- Index queries: Use `iri_to_index`, `label_to_index`, `alt_label_to_index` for lookups
+- Tests: Add test case in `tests/test_folio.py`
+
+**Configuration/Loading Logic:**
+- Implementation: Extend `folio/config.py` for new config options, or `folio/graph.py` for new load/cache logic
+- Pattern: Follow existing patterns in `FOLIOConfiguration`, `load_owl()`, `load_cache()`
+- Maintain backward compatibility with existing cache structure
+
+**Utilities/Helpers:**
+- Simple logging: Use `folio/logger.py` via `get_logger(__name__)`
+- New utility module: Create new file in `folio/` with snake_case name
+- Export in `folio/__init__.py` if part of public API
+
+**Examples / Documentation:**
+- New examples: Add Python file to `examples/` following naming pattern
+- Auto-generated docs: No action needed; Sphinx auto-discovers `folio/` modules
+- Manual documentation: Update `docs/*.md` files
+
+## Special Directories
+
+**~/.folio/cache/:**
+- Purpose: Local cache storage for downloaded ontology files
+- Generated: Yes, created automatically on first FOLIO initialization
+- Committed: No, excluded from git (user-local)
+- Structure: `cache/{source_type}/{blake2b_hash}.owl`
+- Cleanup: Manual deletion of cache/ subdirectory to clear
+
+**htmlcov/:**
+- Purpose: Test coverage report HTML output
+- Generated: Yes, by pytest-cov after test runs
+- Committed: No, excluded from git
+- Usage: Open `htmlcov/index.html` in browser to view coverage
+
+**dist/ and build/:**
+- Purpose: Package distribution artifacts
+- Generated: Yes, by hatchling during `pip install -e .` or `hatch build`
+- Committed: No, excluded from git
+- Cleanup: Safe to delete; will be regenerated as needed
+
+**docs/_build/:**
+- Purpose: Generated Sphinx documentation
+- Generated: Yes, by `sphinx-build` or ReadTheDocs
+- Committed: No, excluded from git
+- Rebuild: `cd docs && make html`
+
+**.pytest_cache/:**
+- Purpose: Pytest metadata and cache
+- Generated: Yes, by pytest
+- Committed: No, excluded from git
+- Cleanup: Safe to delete; regenerated on next test run
+
+---
+
+*Structure analysis: 2026-04-07*
diff --git a/.planning/codebase/TESTING.md b/.planning/codebase/TESTING.md
new file mode 100644
index 0000000..0f75956
--- /dev/null
+++ b/.planning/codebase/TESTING.md
@@ -0,0 +1,335 @@
+# Testing Patterns
+
+**Analysis Date:** 2026-04-07
+
+## Test Framework
+
+**Runner:**
+- `pytest` 8.3.1 - 8.x (configured in `pyproject.toml`)
+- Config: `pyproject.toml` under `[tool.pytest.ini_options]`
+
+**Assertion Library:**
+- Standard `assert` statements (no dedicated assertion library)
+
+**Coverage:**
+- `pytest-cov` 5.0.0 - 5.x
+- Coverage output: `--cov=folio --cov-report=term-missing --cov-report=xml --cov-report=html`
+- Coverage file: `coverage.xml` and HTML report in `htmlcov/`
+
+**Additional Frameworks:**
+- `pytest-asyncio` 0.23.8 - 0.24.x for async test support
+- `pytest-benchmark` 4.0.0 - 5.x for performance benchmarking
+
+**Run Commands:**
+```bash
+# Run all tests with coverage
+pytest
+
+# Run tests with coverage reports (term, xml, html)
+pytest --cov=folio --cov-report=term-missing --cov-report=xml --cov-report=html
+
+# Run specific test file
+pytest tests/test_folio.py
+
+# Run with verbose output
+pytest -v
+
+# Run with markers
+pytest -m marker_name
+```
+
+## Test File Organization
+
+**Location:** `tests/` directory at project root
+
+**Naming:** `test_*.py` pattern
+- Single test file: `tests/test_folio.py` (comprehensive test suite)
+
+**Test file structure:** Module-level fixture definition followed by individual test functions
+
+## Test Structure
+
+**Fixture Definition:**
+```python
+@pytest.fixture(scope="module")
+def folio_graph():
+ return FOLIO()
+```
+
+**Test Functions:**
+- Named with `test_` prefix: `test_list_branches()`, `test_load_owl()`, `test_class_get()`
+- Docstrings describe test purpose
+- Use fixture parameters to access shared resources: `def test_class_count(folio_graph):`
+
+**Test Organization Pattern from `tests/test_folio.py`:**
+
+1. **Fixture Definition** (module-level, scope="module")
+ ```python
+ @pytest.fixture(scope="module")
+ def folio_graph():
+ return FOLIO()
+ ```
+
+2. **Static Method Tests** (no fixture needed)
+ ```python
+ def test_list_branches():
+ """Test the list_branches method of the FOLIO class."""
+ branches = FOLIO.list_branches()
+ assert isinstance(branches, list)
+ assert len(branches) > 1
+ assert "main" in branches
+ ```
+
+3. **Initialization Tests** (testing different constructor paths)
+ ```python
+ def test_load_owl_nocache():
+ """Test the load_owl method of the FOLIO class with the default GitHub repository."""
+ ontology = FOLIO(use_cache=False)
+ assert ontology is not None
+ assert len(ontology) > 0
+ ```
+
+4. **Instance Method Tests** (using fixture)
+ ```python
+ def test_class_get(folio_graph):
+ """Test getting a class from the graph."""
+ edmi = folio_graph["https://folio.openlegalstandard.org/R602916B1A80fDD28d392d3f"]
+ assert edmi is not None
+ assert isinstance(edmi, OWLClass)
+ ```
+
+5. **Error Case Tests** (using `pytest.raises`)
+ ```python
+ def test_list_branches_bad():
+ """Test the list_branches method of the FOLIO class."""
+ with pytest.raises(Exception):
+ branches = FOLIO.list_branches(repo_owner="alea-institute-wrong-name")
+ ```
+
+## Mocking
+
+**Framework:** Not explicitly used in current test suite
+
+**Patterns:** Tests use real external resources (GitHub API, HTTP downloads)
+- Network calls are made to GitHub and raw content URLs
+- Tests assume network connectivity and valid external resources
+- No mock objects or patch decorators observed
+
+**Alternative approach for isolated testing:**
+- Could use `unittest.mock.patch()` for network isolation
+- Could use `responses` library for HTTP mocking
+- Currently, tests validate actual integration with external services
+
+## Fixtures
+
+**Test Data:**
+- Tests use real FOLIO ontology data from GitHub
+- IRIs used: `"https://folio.openlegalstandard.org/R602916B1A80fDD28d392d3f"` (U.S. District Court - W.D. Michigan)
+- Fixture scope: `"module"` - shared across all test functions in the file
+
+**Fixture usage:**
+```python
+# Define fixture
+@pytest.fixture(scope="module")
+def folio_graph():
+ return FOLIO()
+
+# Use in tests
+def test_class_count(folio_graph):
+ assert len(folio_graph.classes) > 18000
+
+def test_class_get(folio_graph):
+ edmi = folio_graph["R602916B1A80fDD28d392d3f"]
+ assert edmi is not None
+```
+
+## Test Coverage
+
+**Current Coverage:**
+- ~50% of code covered (based on `coverage.xml` present)
+- Coverage reports generated in multiple formats: terminal, XML, HTML
+
+**Areas Tested:**
+1. Ontology loading from multiple sources (GitHub, HTTP, cache)
+2. Data model conversion (to_markdown, to_json, to_jsonld, to_owl_xml)
+3. Search functionality (search_by_prefix, search_by_label, search_by_definition)
+4. Type retrieval methods (get_player_actors, get_areas_of_law, etc.)
+5. Triple handling and queries
+6. Object properties and connections
+7. seeAlso relations
+
+**Test File Statistics:**
+- Total lines: ~400
+- Number of test functions: ~30
+- Mix of unit and integration tests
+
+## Test Examples
+
+**Successful Load Test:**
+```python
+def test_load_owl_github():
+ """Test the load_owl method of the FOLIO class with the default GitHub repository."""
+ ontology = FOLIO.load_owl_github()
+ assert ontology is not None
+ assert len(ontology) > 0
+ assert "owl:Ontology" in ontology
+```
+
+**Data Retrieval Test:**
+```python
+def test_class_get(folio_graph):
+ # test a good class by iri
+ edmi = folio_graph["https://folio.openlegalstandard.org/R602916B1A80fDD28d392d3f"]
+ assert edmi is not None
+ assert isinstance(edmi, OWLClass)
+
+ # get by just iri suffix
+ edmi = folio_graph["R602916B1A80fDD28d392d3f"]
+ assert edmi is not None
+ assert isinstance(edmi, OWLClass)
+
+ # get with prefixes
+ edmi = folio_graph["folio:R602916B1A80fDD28d392d3f"]
+ assert edmi is not None
+ assert isinstance(edmi, OWLClass)
+```
+
+**Search Functionality Test:**
+```python
+def test_search_label(folio_graph):
+ for c, score in folio_graph.search_by_label("Georgia"):
+ assert "Georgia" in c.label
+ assert "US+GA" in c.alternative_labels
+ assert score > 0.9
+ break
+
+ for c, score in folio_graph.search_by_label("SDNY"):
+ assert c.label == "U.S. District Court - S.D. New York"
+ assert "S.D.N.Y." in c.alternative_labels
+ assert score > 0.9
+ break
+```
+
+**Error Handling Test:**
+```python
+def test_load_owl_bad_http():
+ """Test the load_owl method of the FOLIO class with the default HTTP URL."""
+ with pytest.raises(Exception):
+ FOLIO.load_owl_http(
+ http_url="https://github.com/alea-institute/FOLIO/raw/main/FOLIO.wol"
+ )
+```
+
+**Property and Connection Test:**
+```python
+def test_object_properties(folio_graph):
+ """Test that object properties are properly parsed from the OWL file."""
+ assert len(folio_graph.object_properties) > 0
+
+ test_property = folio_graph.get_property("https://folio.openlegalstandard.org/R0q5hTo2yTMlnIAbmFnwCH")
+ assert test_property is not None
+ assert test_property.label == "hasFigure"
+
+ opposed_props = folio_graph.get_properties_by_label("folio:opposed")
+ assert len(opposed_props) > 0
+ for prop in opposed_props:
+ assert "opposed" in prop.label or "opposed" in prop.alternative_labels
+```
+
+## Test Async Patterns
+
+**Framework:** `pytest-asyncio` available but not currently used in test suite
+
+**Pattern if needed:**
+```python
+@pytest.mark.asyncio
+async def test_async_function():
+ result = await some_async_function()
+ assert result is not None
+```
+
+## Test Performance
+
+**Benchmarking:**
+- `pytest-benchmark` available in dev dependencies
+- Can be used to track performance regressions
+- Usage: `@pytest.mark.benchmark` decorator on test functions
+
+**Long-running tests:**
+- Ontology loading tests may take several seconds
+- Module-scoped fixture reduces repeat initialization overhead
+- Cache directory at `~/.folio/cache/` stores downloaded ontologies
+
+## Test Types Observed
+
+**Unit Tests:**
+- Data model validation: `test_class_json()`, `test_class_jsonld()`
+- Format conversion: `test_class_markdown()`, `test_class_xml()`
+- Scope: Individual class/method functionality
+
+**Integration Tests:**
+- Full ontology loading: `test_load_owl()`, `test_load_owl_github()`
+- External API integration: `test_list_branches()`, `test_load_owl_http()`
+- Search across entire dataset: `test_search_label()`, `test_search_definitions()`
+- Scope: System-wide functionality, real external dependencies
+
+**Data Integrity Tests:**
+- Verify ontology structure: `test_class_count()` (asserts >18000 classes)
+- Verify relationships: `test_object_properties()`, `test_see_also_relations()`
+- Verify triple consistency: `test_triples()`
+
+## E2E Tests
+
+**Not Explicitly Defined:**
+- Integration tests serve as end-to-end validation
+- Full ontology lifecycle tested: load → parse → query → convert
+- External dependencies (GitHub) are part of test execution
+
+## Running Tests
+
+**Command to run all tests:**
+```bash
+pytest
+```
+
+**With coverage report:**
+```bash
+pytest --cov=folio --cov-report=term-missing --cov-report=xml --cov-report=html
+```
+
+**View HTML coverage:**
+```bash
+# Report generated in htmlcov/index.html
+open htmlcov/index.html
+```
+
+**Run specific test:**
+```bash
+pytest tests/test_folio.py::test_class_get -v
+```
+
+**Run tests with output:**
+```bash
+pytest -v --tb=short
+```
+
+## Known Test Considerations
+
+**Test Dependencies:**
+- Network access required for GitHub API and raw content downloads
+- Tests will fail without internet connectivity
+- External API stability required (GitHub uptime)
+
+**Cache Behavior:**
+- Tests can be run with `use_cache=False` to bypass caching
+- Cached ontologies stored in `~/.folio/cache/` directory
+- Tests may be faster on second run due to caching
+
+**Test Data:**
+- Uses real FOLIO ontology (2.0.0 branch default)
+- IRI references in tests must match actual ontology data
+- Tests brittle to ontology changes (hardcoded IRIs and labels)
+
+---
+
+*Testing analysis: 2026-04-07*
diff --git a/.planning/config.json b/.planning/config.json
new file mode 100644
index 0000000..6989f8f
--- /dev/null
+++ b/.planning/config.json
@@ -0,0 +1,40 @@
+{
+ "model_profile": "quality",
+ "commit_docs": true,
+ "parallelization": true,
+ "search_gitignored": false,
+ "brave_search": false,
+ "firecrawl": false,
+ "exa_search": false,
+ "git": {
+ "branching_strategy": "none",
+ "phase_branch_template": "gsd/phase-{phase}-{slug}",
+ "milestone_branch_template": "gsd/{milestone}-{slug}",
+ "quick_branch_template": null
+ },
+ "workflow": {
+ "research": true,
+ "plan_check": true,
+ "verifier": true,
+ "nyquist_validation": true,
+ "auto_advance": true,
+ "node_repair": true,
+ "node_repair_budget": 2,
+ "ui_phase": true,
+ "ui_safety_gate": true,
+ "text_mode": false,
+ "research_before_questions": false,
+ "discuss_mode": "discuss",
+ "skip_discuss": false,
+ "code_review": true,
+ "code_review_depth": "standard"
+ },
+ "hooks": {
+ "context_warnings": true
+ },
+ "project_code": null,
+ "phase_naming": "sequential",
+ "agent_skills": {},
+ "mode": "yolo",
+ "granularity": "standard"
+}
\ No newline at end of file
diff --git a/.planning/phases/01-data-structure-declarations/01-CONTEXT.md b/.planning/phases/01-data-structure-declarations/01-CONTEXT.md
new file mode 100644
index 0000000..da59dca
--- /dev/null
+++ b/.planning/phases/01-data-structure-declarations/01-CONTEXT.md
@@ -0,0 +1,52 @@
+# Phase 1: Data Structure Declarations - Context
+
+**Gathered:** 2026-04-07
+**Status:** Ready for planning
+**Mode:** Auto-generated (infrastructure phase)
+
+
+## Phase Boundary
+
+FOLIOGraph has all new attributes declared so subsequent phases can populate and query them.
+
+
+
+
+## Implementation Decisions
+
+### Claude's Discretion
+All implementation choices are at Claude's discretion — pure infrastructure phase. Use ROADMAP phase goal, success criteria, and codebase conventions to guide decisions.
+
+
+
+
+## Existing Code Insights
+
+### Key Locations
+- `folio/graph.py:217` — `_label_trie` attribute declaration
+- `folio/graph.py:218` — `_prefix_cache` attribute declaration
+- New attributes should be declared alongside existing trie/cache attributes
+
+### Established Patterns
+- Optional typing with `Optional[marisa_trie.Trie]` for trie attributes
+- Empty dict `{}` for cache initialization
+- Type hints using `Dict[str, List[int]]` pattern
+
+
+
+
+## Specific Ideas
+
+No specific requirements — infrastructure phase. Declare:
+- `_lowercase_label_trie: Optional[marisa_trie.Trie] = None`
+- `_lowercase_to_original: Dict[str, List[str]] = {}`
+- `_ci_prefix_cache: Dict[str, List[OWLClass]] = {}`
+
+
+
+
+## Deferred Ideas
+
+None — discussion stayed within phase scope.
+
+
diff --git a/.planning/phases/01-data-structure-declarations/01-PLAN-1.md b/.planning/phases/01-data-structure-declarations/01-PLAN-1.md
new file mode 100644
index 0000000..6b6ee72
--- /dev/null
+++ b/.planning/phases/01-data-structure-declarations/01-PLAN-1.md
@@ -0,0 +1,19 @@
+# Phase 1: Data Structure Declarations — Plan 1
+
+**Created:** 2026-04-07
+**Status:** Complete
+
+## Goal
+Declare three new attributes on FOLIOGraph for the parallel lowercase trie, bridge mapping dict, and case-insensitive prefix cache.
+
+## Tasks
+1. Add `_lowercase_label_trie: Optional[marisa_trie.Trie] = None` after `_label_trie`
+2. Add `_lowercase_to_original: Dict[str, List[str]] = {}` after the lowercase trie
+3. Add `_ci_prefix_cache: Dict[str, List[OWLClass]] = {}` after `_prefix_cache`
+
+## Files Modified
+- `folio/graph.py` — lines 217-220 (attribute declarations in `__init__`)
+
+## Verification
+- All 27 existing tests pass
+- Zero behavioral change
diff --git a/.planning/phases/02-index-building/02-PLAN-1.md b/.planning/phases/02-index-building/02-PLAN-1.md
new file mode 100644
index 0000000..5a5281a
--- /dev/null
+++ b/.planning/phases/02-index-building/02-PLAN-1.md
@@ -0,0 +1,19 @@
+# Phase 2: Index Building — Plan 1
+
+**Created:** 2026-04-07
+**Status:** Complete
+
+## Goal
+Build the parallel lowercase trie and bridge dict during parse_owl(), and fix pre-existing cache staleness on refresh().
+
+## Tasks
+1. Clear both `_prefix_cache` and `_ci_prefix_cache` at start of trie-building block (fixes refresh() staleness)
+2. Build `_lowercase_to_original` dict mapping `label.casefold()` → `[original_labels]` from all labels meeting MIN_PREFIX_LENGTH
+3. Build `_lowercase_label_trie` from `_lowercase_to_original.keys()`
+
+## Files Modified
+- `folio/graph.py` — trie-building block in `parse_owl()` (after line 1005)
+
+## Verification
+- All 27 existing tests pass
+- Zero behavioral change (new structures populated but not yet queried)
diff --git a/.planning/phases/03-search-api-and-fallback/03-PLAN-1.md b/.planning/phases/03-search-api-and-fallback/03-PLAN-1.md
new file mode 100644
index 0000000..3ce4011
--- /dev/null
+++ b/.planning/phases/03-search-api-and-fallback/03-PLAN-1.md
@@ -0,0 +1,26 @@
+# Phase 3: Search API and Fallback — Plan 1
+
+**Created:** 2026-04-07
+**Status:** Complete
+
+## Goal
+Wire case-insensitive search through both trie and pure-Python paths with proper deduplication.
+
+## Tasks
+1. Add `case_sensitive: bool = False` parameter to `search_by_prefix()`
+2. Split into `_search_by_prefix_sensitive()` (original behavior) and `_search_by_prefix_insensitive()` (new)
+3. Insensitive path: query `_lowercase_label_trie` with `prefix.casefold()`, resolve through bridge dict
+4. Insensitive path: deduplicate results by IRI index using `seen` set
+5. Insensitive path: sort original keys by length after bridge dict expansion
+6. Pure-Python fallback: apply `casefold()` to both prefix and labels
+7. Separate caches: `_prefix_cache` for CS, `_ci_prefix_cache` for CI (keyed by `prefix.casefold()`)
+
+## Files Modified
+- `folio/graph.py` — replaced `search_by_prefix()` with three methods
+
+## Verification
+- `search_by_prefix("securit")` → 31 results (was 0)
+- `search_by_prefix("dui")` → 2 results (was 0)
+- `case_sensitive=True` preserves original behavior
+- 0 duplicates in CI results
+- Existing test_search_prefix needs update in Phase 4 (default changed to CI)
diff --git a/.planning/phases/04-test-suite/04-PLAN-1.md b/.planning/phases/04-test-suite/04-PLAN-1.md
new file mode 100644
index 0000000..3afe109
--- /dev/null
+++ b/.planning/phases/04-test-suite/04-PLAN-1.md
@@ -0,0 +1,22 @@
+# Phase 4: Test Suite — Plan 1
+
+**Created:** 2026-04-07
+**Status:** Complete
+
+## Goal
+Validate correctness, backward compatibility, and edge case handling with automated tests.
+
+## Tasks
+1. Update existing `test_search_prefix` to use `case_sensitive=True` (preserves original assertion)
+2. Add `test_search_prefix_case_insensitive` — lowercase "securit" matches title-case labels
+3. Add `test_search_prefix_case_insensitive_acronym` — "dui" matches "DUI"/"Driving Under the Influence"
+4. Add `test_search_prefix_case_sensitive_preserves_behavior` — CS=True: "securit"→0, "Securit"→results
+5. Add `test_search_prefix_no_duplicates` — no duplicate OWLClass IRIs in CI results
+6. Add `test_search_prefix_fallback_parity` — monkeypatch trie to None, verify fallback matches trie results
+
+## Files Modified
+- `tests/test_folio.py` — updated 1 test, added 5 new tests
+
+## Verification
+- 32 tests pass (up from 27)
+- 1 pre-existing error (benchmark fixture not installed) — unrelated
diff --git a/.planning/quick/260408-9yz-address-pr-16-review-feedback-mechanical/260408-9yz-PLAN.md b/.planning/quick/260408-9yz-address-pr-16-review-feedback-mechanical/260408-9yz-PLAN.md
new file mode 100644
index 0000000..2ed3c9c
--- /dev/null
+++ b/.planning/quick/260408-9yz-address-pr-16-review-feedback-mechanical/260408-9yz-PLAN.md
@@ -0,0 +1,227 @@
+---
+phase: quick
+plan: 260408-9yz
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+ - folio/graph.py
+ - tests/test_folio.py
+autonomous: true
+requirements: [PR-16-review-feedback]
+
+must_haves:
+ truths:
+ - "ruff check passes with zero errors on folio/ and tests/"
+ - "ruff format --check passes on folio/graph.py and tests/test_folio.py"
+ - "Case-sensitive search returns no duplicate OWLClass entries for same IRI"
+ - "Case-insensitive search returns no duplicate OWLClass entries for same IRI"
+ - "Primary-label matches rank before alt-label matches in both search paths"
+ - "Fallback (pure-Python) path produces same IRIs as trie path"
+ - "All existing tests pass, new tests pass"
+ artifacts:
+ - path: "folio/graph.py"
+ provides: "Dedup-by-IRI + label-over-alt-label ranking on both search paths"
+ - path: "tests/test_folio.py"
+ provides: "Updated tests: monkeypatch cleanup, dedup assertions, ranking assertions"
+ key_links:
+ - from: "tests/test_folio.py::test_search_prefix_fallback_parity"
+ to: "folio.graph.marisa_trie"
+ via: "monkeypatch.setattr"
+ pattern: "monkeypatch.setattr.*marisa_trie.*None"
+---
+
+
+Address PR #16 review feedback from mjbommar: mechanical lint/format cleanups, dedup-with-tiebreak on both case-sensitive and case-insensitive prefix search paths, label-over-alt-label ranking, and corresponding test updates.
+
+Purpose: Resolve reviewer comments so PR can be merged.
+Output: Clean folio/graph.py and tests/test_folio.py, three atomic commits.
+
+
+
+@$HOME/.claude/get-shit-done/workflows/execute-plan.md
+@$HOME/.claude/get-shit-done/templates/summary.md
+
+
+
+@folio/graph.py (lines 1307-1401: search_by_prefix, _search_by_prefix_sensitive, _search_by_prefix_insensitive)
+@tests/test_folio.py (lines 256-316: all prefix search tests)
+
+
+From folio/graph.py:
+```python
+# Type annotations for key attributes
+self.label_to_index: Dict[str, List[int]] = {}
+self.alt_label_to_index: Dict[str, List[int]] = {}
+self._lowercase_to_original: Dict[str, List[str]] = {}
+self._label_trie: Optional[marisa_trie.Trie] = None # line 217
+self._lowercase_label_trie: Optional[marisa_trie.Trie] = None # line 218
+self._prefix_cache: Dict[str, List[OWLClass]] = {} # line 220
+self._ci_prefix_cache: Dict[str, List[OWLClass]] = {} # line 221
+
+def __getitem__(self, item: str | int) -> Optional[OWLClass]: # line 1164
+def search_by_prefix(self, prefix: str, case_sensitive: bool = False) -> List[OWLClass]: # line 1307
+def _search_by_prefix_sensitive(self, prefix: str) -> List[OWLClass]: # line 1327
+def _search_by_prefix_insensitive(self, prefix: str) -> List[OWLClass]: # line 1354
+```
+
+The `marisa_trie` module is conditionally imported at module level (line 138-141). When unavailable, it's set to `None`. The fallback code path checks `marisa_trie is not None` at module level.
+
+
+
+
+
+
+ Task 1: Mechanical cleanups -- lint, format, monkeypatch, ty diagnostics
+ folio/graph.py, tests/test_folio.py
+
+1. In `tests/test_folio.py`, rewrite `test_search_prefix_fallback_parity` to use idiomatic pytest monkeypatch:
+ - Remove `import folio.graph as graph_module` (line 303) -- this is the ruff F401 unused import.
+ - Replace the manual `_lowercase_label_trie = None` / try-finally with:
+ ```python
+ import folio.graph
+ monkeypatch.setattr(folio.graph, "marisa_trie", None)
+ folio_graph._ci_prefix_cache = {}
+ ```
+ This triggers the `else` branch in `_search_by_prefix_insensitive` (which checks `marisa_trie is not None`).
+ - Also clear `_ci_prefix_cache` so cached trie results don't short-circuit.
+ - Remove the try/finally block entirely -- monkeypatch auto-restores.
+ - Make sure `import folio.graph` is at the TOP of the test file (with other imports), NOT inside the function.
+
+2. Add `# type: ignore[union-attribute]` to the 2 lines in `_search_by_prefix_sensitive` referencing `self._label_trie.keys(prefix)` (line 1333). These mirror the ty diagnostic for the optional trie type.
+
+3. Add `# type: ignore[union-attribute]` to the corresponding line in `_search_by_prefix_insensitive` referencing `self._lowercase_label_trie.keys(folded)` (line 1363).
+
+4. For the `.get(key, [])` ty errors (no-matching-overload) in both methods: These are Dict[str, List[int]].get(str, list[Never]) issues. Add `# type: ignore[no-matching-overload]` on the affected `.get(key, [])` lines in both methods (lines 1347, 1348, 1370, 1390, 1394).
+
+5. For the cache assignment ty errors (list[OWLClass | None] vs list[OWLClass]): Add `# type: ignore[invalid-assignment]` on the cache assignment lines (1351, 1400) and `# type: ignore[return-type]` on the return lines if flagged (1352, 1401).
+
+6. Run `uvx ruff format folio/graph.py tests/test_folio.py` to fix any formatting issues.
+
+7. Run `uvx ruff check folio/ tests/` to confirm zero errors.
+
+
+ cd "/home/damienriehl/Coding Projects/folio-python" && uvx ruff check folio/ tests/ && uvx ruff format --check folio/graph.py tests/test_folio.py
+
+ ruff check returns 0 errors, ruff format --check passes, no unused imports, monkeypatch is idiomatic, ty diagnostics addressed with type: ignore comments matching the pre-existing pattern in _search_by_prefix_sensitive.
+
+
+
+ Task 2: Dedup-with-tiebreak and label-over-alt-label ranking on both search paths
+ folio/graph.py
+
+**In `_search_by_prefix_sensitive` (line 1327):**
+
+1. Change the sort key for `keys` from `key=len` to `key=lambda k: (k not in self.label_to_index, len(k))`. This sorts primary-label keys first (False < True), then by length within each group. Apply this to BOTH the trie path (line 1333) and the pure-Python fallback path (lines 1335-1343).
+
+2. Replace the current no-dedup loop (lines 1345-1348):
+ ```python
+ iri_list = []
+ for key in keys:
+ iri_list.extend(self.label_to_index.get(key, []))
+ iri_list.extend(self.alt_label_to_index.get(key, []))
+ ```
+ With a dedup-by-index loop matching the pattern already in `_search_by_prefix_insensitive`:
+ ```python
+ seen: set = set()
+ iri_list: list = []
+ for key in keys:
+ for idx in self.label_to_index.get(key, []): # type: ignore[no-matching-overload]
+ if idx not in seen:
+ seen.add(idx)
+ iri_list.append(idx)
+ for idx in self.alt_label_to_index.get(key, []): # type: ignore[no-matching-overload]
+ if idx not in seen:
+ seen.add(idx)
+ iri_list.append(idx)
+ ```
+
+**In `_search_by_prefix_insensitive` (line 1354):**
+
+3. Change the sort key for `original_keys` from `key=len` to `key=lambda k: (k not in self.label_to_index, len(k))`. Apply this to BOTH the trie path (line 1366-1373) and the pure-Python fallback path (lines 1376-1384). The trie path sorts `original_keys`, NOT `lowercase_keys` -- the sort key references `self.label_to_index` which uses original-case keys.
+
+4. The existing dedup loop (lines 1387-1397) already does dedup-by-index. The label-over-alt-label ranking is now handled by the sort key change, so the `seen` set naturally encounters primary-label indices first. No structural change needed to the dedup loop.
+
+**Why this works:** Since keys are sorted with primary-label matches first, when iterating and adding to `seen`, a primary-label match for an IRI will be encountered before its alt-label match. The dedup `seen` set then correctly skips the alt-label duplicate.
+
+
+ cd "/home/damienriehl/Coding Projects/folio-python" && uv run pytest tests/test_folio.py::test_search_prefix tests/test_folio.py::test_search_prefix_no_duplicates tests/test_folio.py::test_search_prefix_case_insensitive tests/test_folio.py::test_search_prefix_fallback_parity -v
+
+ Both _search_by_prefix_sensitive and _search_by_prefix_insensitive use identical dedup-by-IRI-index pattern. Sort key is (is_alt_label, len) on both paths and both branches (trie + fallback). Existing tests pass.
+
+
+
+ Task 3: Update and add tests for dedup and ranking behavior
+ tests/test_folio.py
+
+1. **Update `test_search_prefix`** (line 256): Verify it still passes -- the first result for `search_by_prefix("Mich", case_sensitive=True)` should still be "Michigan" since it's a primary label match and shortest.
+
+2. **Add `test_search_prefix_case_sensitive_no_duplicates`**: Search for a prefix that previously produced duplicates in case-sensitive mode (e.g., "Mich" which matched Michigan in both label_to_index and alt_label_to_index). Assert no duplicate IRIs:
+ ```python
+ def test_search_prefix_case_sensitive_no_duplicates(folio_graph):
+ """Case-sensitive search returns no duplicate OWLClass entries."""
+ results = folio_graph.search_by_prefix("Mich", case_sensitive=True)
+ iris = [c.iri for c in results]
+ assert len(iris) == len(set(iris)), f"Duplicate IRIs in case-sensitive results: {iris}"
+ ```
+
+3. **Add `test_search_prefix_primary_label_ranks_first`**: For `search_by_prefix("Cal")`, verify that "California" (primary label match) appears before any alt-label-only match (like a reporter code "CAL" that maps to a different concept). Test both case-sensitive and case-insensitive:
+ ```python
+ def test_search_prefix_primary_label_ranks_first(folio_graph):
+ """Primary-label matches rank before alt-label matches for same prefix."""
+ results = folio_graph.search_by_prefix("Cal")
+ labels = [c.label for c in results]
+ # California is a primary label starting with "Cal", should appear early
+ if "California" in labels:
+ cal_idx = labels.index("California")
+ # California should be near the top (within first few results)
+ assert cal_idx < 5, f"California at index {cal_idx}, expected near top"
+
+ # Also verify case-sensitive path
+ results_cs = folio_graph.search_by_prefix("Cal", case_sensitive=True)
+ labels_cs = [c.label for c in results_cs]
+ if "California" in labels_cs:
+ cal_idx_cs = labels_cs.index("California")
+ assert cal_idx_cs < 5, f"California at index {cal_idx_cs} in case-sensitive, expected near top"
+ ```
+
+4. **Update `test_search_prefix_fallback_parity`**: The fallback parity test (rewritten in Task 1 with monkeypatch) should still assert IRI set equality. Also add a check that the ordering is the same (not just set equality), since both paths now use the same sort key:
+ ```python
+ # After getting trie_iris and fallback_iris (both sorted by IRI):
+ assert trie_iris == fallback_iris
+ # Also check ordering matches (labels in same order)
+ trie_labels = [c.label for c in trie_results]
+ fallback_labels = [c.label for c in fallback_results]
+ assert trie_labels == fallback_labels, "Trie and fallback ordering differ"
+ ```
+
+5. Run the full test suite: `uv run pytest tests/ -v`
+
+
+ cd "/home/damienriehl/Coding Projects/folio-python" && uv run pytest tests/ -v
+
+ All existing tests pass. New tests verify: (1) case-sensitive dedup (no duplicate IRIs), (2) primary-label-first ranking for both paths, (3) fallback parity includes ordering not just set equality. Full test suite green.
+
+
+
+
+
+1. `uvx ruff check folio/ tests/` -- zero errors
+2. `uvx ruff format --check folio/graph.py tests/test_folio.py` -- already formatted
+3. `uv run pytest tests/ -v` -- all tests pass
+4. Manual review: `_search_by_prefix_sensitive` and `_search_by_prefix_insensitive` have symmetric structure (both dedup, both use same sort key pattern)
+
+
+
+- Zero ruff lint errors, formatting clean
+- ty diagnostics addressed with type: ignore comments (matching reviewer-approved approach)
+- Both search paths dedup by IRI index
+- Both search paths sort primary-label matches before alt-label matches
+- Fallback (pure-Python) path produces identical results and ordering to trie path
+- Full test suite passes with new dedup and ranking assertions
+- Three clean commits: (1) mechanical cleanups, (2) dedup + ranking logic, (3) test updates
+
+
+
diff --git a/.planning/quick/260408-9yz-address-pr-16-review-feedback-mechanical/260408-9yz-SUMMARY.md b/.planning/quick/260408-9yz-address-pr-16-review-feedback-mechanical/260408-9yz-SUMMARY.md
new file mode 100644
index 0000000..e9ce4e3
--- /dev/null
+++ b/.planning/quick/260408-9yz-address-pr-16-review-feedback-mechanical/260408-9yz-SUMMARY.md
@@ -0,0 +1,70 @@
+---
+phase: quick
+plan: 260408-9yz
+subsystem: folio/graph.py prefix search
+tags: [pr-feedback, dedup, ranking, lint, tests]
+dependency_graph:
+ requires: [folio/graph.py, tests/test_folio.py]
+ provides: [dedup-by-IRI, label-over-alt-label ranking, monkeypatch cleanup]
+ affects: [search_by_prefix API behavior]
+tech_stack:
+ added: []
+ patterns: [dedup-by-index with seen set, tuple sort key for label-first ranking]
+key_files:
+ created: []
+ modified:
+ - folio/graph.py
+ - tests/test_folio.py
+decisions:
+ - "Relaxed fallback parity test to IRI set equality only (not ordering) because trie and pure-Python paths return same-length keys in different order within ties"
+ - "Used (k not in label_to_index, len(k)) sort key instead of alphabetical tiebreak -- simpler and sufficient for ranking correctness"
+ - "Used monkeypatch.setattr on folio.graph.marisa_trie module-level variable instead of patching instance._lowercase_label_trie -- triggers the correct code path naturally"
+metrics:
+ duration: "4m 34s"
+ completed: "2026-04-08T12:20:48Z"
+ tasks_completed: 3
+ tasks_total: 3
+ files_modified: 2
+---
+
+# Quick Task 260408-9yz: Address PR #16 Review Feedback (Mechanical) Summary
+
+Dedup-by-IRI-index and label-over-alt-label ranking on both case-sensitive and case-insensitive prefix search paths, with idiomatic monkeypatch test cleanup and ty diagnostic suppression.
+
+## Task Results
+
+| Task | Name | Commit | Key Changes |
+|------|------|--------|-------------|
+| 1 | Mechanical cleanups -- lint, format, monkeypatch, ty | 510b425 | Removed unused import, rewrote fallback test with monkeypatch.setattr, added type: ignore comments, ran ruff format |
+| 2 | Dedup-with-tiebreak and label-first ranking | 6890a2a | Added seen-set dedup to _search_by_prefix_sensitive, changed sort key to (not-in-label_to_index, len) on all 4 code paths |
+| 3 | Tests for dedup and ranking | 4b8262a | Added CS dedup test, primary-label-first ranking test, updated fallback parity to IRI set equality |
+
+## Verification Results
+
+- `uvx ruff check folio/ tests/` -- zero errors
+- `uvx ruff format --check folio/graph.py tests/test_folio.py` -- already formatted
+- `uv run pytest tests/ -v` -- 45/45 passed
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1 - Bug] Relaxed California ranking assertion threshold**
+- **Found during:** Task 3
+- **Issue:** Plan suggested `assert cal_idx < 5` for "California" with prefix "Cal", but 6 shorter primary-label matches (Caldas, Calista, Calabria, etc.) push California to index 6
+- **Fix:** Changed test to use "Mich"/Michigan which is a shorter primary label and reliably first. Tests Michigan is first result for case-sensitive, and within top 5 for case-insensitive.
+- **Files modified:** tests/test_folio.py
+- **Commit:** 4b8262a
+
+**2. [Rule 1 - Bug] Removed ordering assertion from fallback parity test**
+- **Found during:** Task 3
+- **Issue:** Plan suggested asserting `trie_labels == fallback_labels` for ordering parity, but same-length primary labels (e.g., "Securities Fraud" vs "Security Deposit", both 16 chars) appear in different order between trie and pure-Python paths due to different iteration order
+- **Fix:** Test asserts only IRI set equality (sorted IRI lists match). Ordering within length-ties is an implementation detail, not a correctness requirement.
+- **Files modified:** tests/test_folio.py
+- **Commit:** 4b8262a
+
+## Known Stubs
+
+None -- all code paths are fully implemented.
+
+## Self-Check: PASSED
diff --git a/.planning/research/ARCHITECTURE.md b/.planning/research/ARCHITECTURE.md
new file mode 100644
index 0000000..f76878d
--- /dev/null
+++ b/.planning/research/ARCHITECTURE.md
@@ -0,0 +1,367 @@
+# Architecture: Parallel Lowercase Trie for Case-Insensitive Prefix Search
+
+**Domain:** FOLIO ontology graph — prefix search subsystem
+**Researched:** 2026-04-07
+**Confidence:** HIGH (all integration points verified against existing source)
+
+## Current Architecture (Baseline)
+
+### Data Flow: Label Ingestion to Search Result
+
+```
+parse_owl_class() [line 740-773]
+ |
+ +--> label_to_index: Dict[str, List[int]] # "Securities Fraud" -> [42]
+ +--> alt_label_to_index: Dict[str, List[int]] # "DUI" -> [17]
+ |
+ v
+parse_owl() [line 1004-1012] (end of method, after all nodes parsed)
+ |
+ +--> _label_trie: marisa_trie.Trie(all_labels) # built from both dicts' keys
+ |
+ v
+search_by_prefix("Securit") [line 1289-1333]
+ |
+ +--> _prefix_cache check (exact prefix string)
+ +--> _label_trie.keys("Securit") # returns ["Securities Fraud", ...]
+ +--> label_to_index / alt_label_to_index lookup # label -> List[int] indices
+ +--> self[index] for each # int -> OWLClass via self.classes[index]
+ +--> cache result in _prefix_cache[prefix]
+```
+
+### Key Data Structures
+
+| Attribute | Type | Purpose |
+|-----------|------|---------|
+| `label_to_index` | `Dict[str, List[int]]` | Original-case label -> class indices |
+| `alt_label_to_index` | `Dict[str, List[int]]` | Original-case alt/preferred label -> class indices |
+| `_label_trie` | `marisa_trie.Trie` or `None` | Case-sensitive prefix lookup (keys from both dicts) |
+| `_prefix_cache` | `Dict[str, List[OWLClass]]` | Memoized results keyed by exact prefix string |
+| `classes` | `List[OWLClass]` | Master list; integer indices resolve to objects |
+
+### Critical Observations
+
+1. **Index-based resolution.** Both `label_to_index` and `alt_label_to_index` map strings to `List[int]` (indices into `self.classes`). The trie only stores keys; it does not store values. The trie's job is prefix-matching; the dicts handle key-to-index resolution.
+
+2. **Pure-Python fallback.** When `marisa_trie` is `None`, `search_by_prefix` falls back to a linear scan of both dicts' keys with `str.startswith()`. The fallback must also gain case-insensitive support.
+
+3. **Cache is prefix-exact.** `_prefix_cache["Securit"]` and `_prefix_cache["securit"]` are separate entries today. No normalization.
+
+4. **Trie is built once** at the end of `parse_owl()`, after all classes have been parsed and indexed. The `refresh()` method calls `parse_owl()` again (after clearing all data structures), so the trie is rebuilt.
+
+5. **`refresh()` clears dicts but not the trie or cache explicitly.** It clears `label_to_index` and `alt_label_to_index` (line 1262-1263) but relies on `parse_owl()` reassigning `_label_trie`. The `_prefix_cache` is not cleared in `refresh()` -- this is a pre-existing issue, but any new attributes should follow the same pattern (or fix it).
+
+---
+
+## Recommended Architecture
+
+### New Data Structures
+
+Add three new attributes to `__init__`:
+
+```python
+# Case-insensitive search structures
+self._lowercase_label_trie: Optional[marisa_trie.Trie] = None
+self._lowercase_to_original: Dict[str, List[str]] = {}
+self._ci_prefix_cache: Dict[str, List[OWLClass]] = {}
+```
+
+| Attribute | Type | Purpose |
+|-----------|------|---------|
+| `_lowercase_label_trie` | `marisa_trie.Trie` or `None` | Lowercase prefix lookup |
+| `_lowercase_to_original` | `Dict[str, List[str]]` | Maps lowercase key -> list of original-case keys |
+| `_ci_prefix_cache` | `Dict[str, List[OWLClass]]` | Cache for case-insensitive results, keyed by lowercased prefix |
+
+### Why a Separate Mapping Dict (Not Embedded in Trie Values)
+
+`marisa_trie.Trie` is a pure key set -- it stores strings, not key-value pairs. (`BytesTrie` and `RecordTrie` can store values, but they add complexity and aren't needed here.) The cleanest approach: use the plain `Trie` for prefix matching, then resolve lowercase keys back to originals via `_lowercase_to_original`, which then feeds into the existing `label_to_index` / `alt_label_to_index` dicts.
+
+An alternative would be `marisa_trie.RecordTrie` mapping lowercase keys to integer indices directly, but this would bypass the existing resolution path and create a parallel index system -- more surface area for bugs, no real performance gain at ~18K entries.
+
+### Data Flow: Lowercase Trie Key to OWLClass
+
+```
+search_by_prefix("securit", case_sensitive=False) # caller input
+ |
+ +--> normalize: prefix_lower = "securit"
+ +--> _ci_prefix_cache check (prefix_lower)
+ |
+ +--> _lowercase_label_trie.keys("securit") # ["securities fraud", "security", ...]
+ |
+ +--> For each lowercase_key:
+ | _lowercase_to_original["securities fraud"] # ["Securities Fraud"]
+ | _lowercase_to_original["security"] # ["Security"]
+ |
+ +--> For each original_key:
+ | label_to_index.get("Securities Fraud", []) # [42]
+ | alt_label_to_index.get("Securities Fraud", [])# []
+ |
+ +--> self[index] for each index # OWLClass objects
+ +--> deduplicate (same OWLClass reachable via label + alt_label)
+ +--> cache in _ci_prefix_cache[prefix_lower]
+```
+
+### Why `_lowercase_to_original` Maps to `List[str]`, Not `str`
+
+Multiple original labels can collide when lowercased. For example, if FOLIO contained both "DUI" and "Dui" (hypothetical), both lowercase to "dui". The mapping must be `str -> List[str]` to handle this without data loss. In practice, collisions are rare in FOLIO (~18K concepts), but correctness requires the list.
+
+---
+
+## Integration Points
+
+### 1. Build Site: `parse_owl()` (line 1004-1012)
+
+The lowercase trie and mapping dict should be built immediately after the existing trie, in the same method, using the same label pool. This keeps the two tries synchronized and avoids a separate build pass.
+
+```python
+# EXISTING (unchanged):
+if marisa_trie is not None:
+ all_labels = [
+ label
+ for label in list(self.label_to_index.keys())
+ + list(self.alt_label_to_index.keys())
+ if len(label) >= MIN_PREFIX_LENGTH
+ ]
+ self._label_trie = marisa_trie.Trie(all_labels)
+
+ # NEW: build lowercase trie and reverse mapping
+ self._lowercase_to_original = {}
+ for label in all_labels:
+ lower = label.lower()
+ if lower not in self._lowercase_to_original:
+ self._lowercase_to_original[lower] = [label]
+ else:
+ if label not in self._lowercase_to_original[lower]:
+ self._lowercase_to_original[lower].append(label)
+ self._lowercase_label_trie = marisa_trie.Trie(
+ list(self._lowercase_to_original.keys())
+ )
+```
+
+**Build order:** The mapping dict MUST be built before the lowercase trie, because `_lowercase_to_original.keys()` provides the deduplicated lowercase key set for the trie. Building the trie from `[l.lower() for l in all_labels]` directly would include duplicates, which `marisa_trie.Trie` silently deduplicates -- but it is cleaner to build the dict first and derive trie keys from it.
+
+### 2. Search Site: `search_by_prefix()` (line 1289-1333)
+
+Add `case_sensitive: bool = False` parameter. Branch on it.
+
+```python
+def search_by_prefix(
+ self, prefix: str, case_sensitive: bool = False
+) -> List[OWLClass]:
+ # Determine cache and effective prefix
+ if case_sensitive:
+ cache = self._prefix_cache
+ effective_prefix = prefix
+ else:
+ cache = self._ci_prefix_cache
+ effective_prefix = prefix.lower()
+
+ # Check cache
+ if effective_prefix in cache:
+ return cache[effective_prefix]
+
+ # Trie path
+ if marisa_trie is not None:
+ if case_sensitive:
+ keys = sorted(self._label_trie.keys(effective_prefix), key=len)
+ else:
+ lowercase_keys = sorted(
+ self._lowercase_label_trie.keys(effective_prefix), key=len
+ )
+ # Expand lowercase keys to original keys
+ keys = []
+ for lk in lowercase_keys:
+ keys.extend(self._lowercase_to_original.get(lk, []))
+ else:
+ # Pure-Python fallback
+ all_labels = (
+ list(self.label_to_index.keys())
+ + list(self.alt_label_to_index.keys())
+ )
+ if case_sensitive:
+ keys = sorted(
+ [l for l in all_labels if l.startswith(effective_prefix)],
+ key=len,
+ )
+ else:
+ keys = sorted(
+ [l for l in all_labels if l.lower().startswith(effective_prefix)],
+ key=len,
+ )
+
+ # Resolve keys to OWLClass (same as existing)
+ iri_list = []
+ for key in keys:
+ iri_list.extend(self.label_to_index.get(key, []))
+ iri_list.extend(self.alt_label_to_index.get(key, []))
+
+ # Deduplicate while preserving order
+ seen = set()
+ unique_indices = []
+ for idx in iri_list:
+ if idx not in seen:
+ seen.add(idx)
+ unique_indices.append(idx)
+
+ classes = [self[index] for index in unique_indices]
+ cache[effective_prefix] = classes
+ return classes
+```
+
+### 3. Cache Strategy
+
+**Two separate caches, not one.** The case-sensitive cache (`_prefix_cache`) is keyed by original-case prefix; the case-insensitive cache (`_ci_prefix_cache`) is keyed by lowercased prefix. This prevents cross-contamination: `_prefix_cache["Securit"]` returns only exact-case matches; `_ci_prefix_cache["securit"]` returns all case variants.
+
+**Normalization on the case-insensitive side:** All lookups into `_ci_prefix_cache` use `prefix.lower()` as the key. This means `search_by_prefix("Securit", case_sensitive=False)` and `search_by_prefix("securit", case_sensitive=False)` share the same cache entry. This is the "shared cache for case variants" behavior the PROJECT.md calls for.
+
+**Alternative considered and rejected:** A single unified cache with a `(prefix, case_sensitive)` tuple key. This works but mixes concerns -- the case-insensitive cache should normalize keys to lowercase, which a tuple key does not enforce. Two caches are simpler and less error-prone.
+
+### 4. `__init__` Initialization (line 217-218)
+
+Add new attributes alongside existing ones:
+
+```python
+self._label_trie: Optional[marisa_trie.Trie] = None
+self._lowercase_label_trie: Optional[marisa_trie.Trie] = None
+self._lowercase_to_original: Dict[str, List[str]] = {}
+self._prefix_cache: Dict[str, List[OWLClass]] = {}
+self._ci_prefix_cache: Dict[str, List[OWLClass]] = {}
+```
+
+### 5. `refresh()` Method (line 1250-1287)
+
+`refresh()` calls `parse_owl()` which rebuilds both tries and the mapping dict. The new `_ci_prefix_cache` should be cleared in `refresh()` -- or, since the existing `_prefix_cache` is not explicitly cleared in `refresh()` either (a pre-existing oversight; `parse_owl` reassigns `_label_trie` but the old cache entries become stale), the safest approach is to reset both caches in `parse_owl()` at the top of the trie-building block:
+
+```python
+# At the start of the trie-building section in parse_owl():
+self._prefix_cache = {}
+self._ci_prefix_cache = {}
+```
+
+This fixes the pre-existing staleness issue for the original cache and prevents it for the new one.
+
+---
+
+## Component Boundaries
+
+| Component | Responsibility | Touches |
+|-----------|---------------|---------|
+| `parse_owl_class()` | Populate `label_to_index`, `alt_label_to_index` | No change needed |
+| `parse_owl()` (trie section) | Build both tries + mapping dict | Add lowercase trie + mapping build |
+| `search_by_prefix()` | Route to correct trie + cache based on `case_sensitive` | Add branching logic |
+| `__init__` | Initialize all data structures | Add 3 new attributes |
+| `refresh()` / `parse_owl()` | Reset stale state | Clear both caches |
+
+**Boundary principle:** The `_lowercase_to_original` dict is an internal bridge between the lowercase trie and the existing label dicts. It should never be exposed in the public API. Callers interact only with `search_by_prefix(prefix, case_sensitive=...)`.
+
+---
+
+## Patterns to Follow
+
+### Pattern: Parallel Index With Bridge Dict
+
+**What:** A secondary index (lowercase trie) that maps back to the primary index (original-case label dicts) through a bridge dict (`_lowercase_to_original`).
+
+**Why this pattern:** The existing label-to-index dicts are the source of truth for resolving labels to `OWLClass` objects. Rather than duplicating this resolution logic, the lowercase trie feeds back into the same dicts. One resolution path, two entry points.
+
+```
+ case_sensitive=True case_sensitive=False
+ | |
+ _label_trie _lowercase_label_trie
+ | |
+ original key lowercase key
+ | |
+ | _lowercase_to_original
+ | |
+ +------- original key(s) ---------------+
+ |
+ label_to_index / alt_label_to_index
+ |
+ List[int] indices
+ |
+ self.classes[idx]
+ |
+ OWLClass
+```
+
+### Pattern: Normalize-on-Entry for Cache
+
+**What:** Normalize the cache key at the entry point of the method, before any logic runs. All downstream code uses the normalized key.
+
+**Why:** Prevents cache fragmentation. If normalization happens inconsistently (sometimes before cache check, sometimes after), you get duplicate entries.
+
+```python
+# Correct: normalize once, use everywhere
+effective_prefix = prefix.lower() if not case_sensitive else prefix
+if effective_prefix in cache:
+ return cache[effective_prefix]
+# ... compute ...
+cache[effective_prefix] = result
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+### Anti-Pattern: Lowercasing the Existing Dicts
+
+**What:** Making `label_to_index` store lowercase keys instead of original-case.
+
+**Why bad:** Destroys original case information. `get_by_label("Securities Fraud")` would break. The existing dicts serve multiple purposes beyond prefix search.
+
+### Anti-Pattern: Building Lowercase Trie From Indices Directly
+
+**What:** Having `_lowercase_label_trie` store `(lowercase_key, index)` pairs via `RecordTrie`, bypassing `label_to_index`/`alt_label_to_index` entirely.
+
+**Why bad:** Creates a parallel resolution path. Bugs where one path returns different results than the other. More code, more maintenance, no performance benefit at 18K scale.
+
+### Anti-Pattern: Shared Cache With Type-Switching
+
+**What:** One `_prefix_cache` dict storing both case-sensitive and case-insensitive results, using heuristics to decide which was stored.
+
+**Why bad:** Impossible to distinguish `_prefix_cache["dui"]` as a case-sensitive search for the literal "dui" vs a case-insensitive search that was normalized. Two caches, clearly separated, are unambiguous.
+
+---
+
+## Deduplication Concern
+
+When case-insensitive searching, the same `OWLClass` may be reachable through multiple paths:
+- "Securities Fraud" (via `label_to_index`) and "securities fraud" (via `_lowercase_to_original` -> "Securities Fraud" -> same dict)
+- An OWLClass whose `label` and `preferred_label` both start with the prefix
+
+The existing `search_by_prefix` does NOT deduplicate -- it can return the same OWLClass multiple times if the same class is indexed under both `label_to_index` and `alt_label_to_index`. This is pre-existing behavior. The new case-insensitive path should add deduplication (using a `seen` set on indices) because the probability of duplicates increases when multiple original-case keys map to the same lowercase key. This is a net improvement.
+
+---
+
+## Memory Impact
+
+| Structure | Estimated Size | Notes |
+|-----------|---------------|-------|
+| `_lowercase_label_trie` | ~200-400 KB | Same order as existing trie (~18K labels, MARISA is highly compressed) |
+| `_lowercase_to_original` | ~1-2 MB | 18K entries, each a list of 1-2 strings |
+| `_ci_prefix_cache` | Grows with usage | Same growth pattern as existing cache |
+
+Total additional memory: ~2-3 MB. Negligible for a library that already holds the full FOLIO ontology in memory.
+
+---
+
+## Build Order Implications for Implementation
+
+1. **First:** Add the three new attributes to `__init__` (safe, no behavioral change)
+2. **Second:** Build `_lowercase_to_original` and `_lowercase_label_trie` in `parse_owl()` (safe, existing behavior unchanged since `search_by_prefix` doesn't use them yet)
+3. **Third:** Modify `search_by_prefix()` to accept `case_sensitive` parameter and branch (behavioral change, but default `False` is the desired new behavior)
+4. **Fourth:** Update pure-Python fallback to also support case-insensitive search
+5. **Fifth:** Add cache clearing in `parse_owl()` for both caches
+6. **Sixth:** Add deduplication to result assembly
+7. **Last:** Tests
+
+Steps 1-2 can be done together. Steps 3-6 can be done together. Tests come after the implementation is complete.
+
+---
+
+## Sources
+
+- [marisa-trie documentation](https://marisa-trie.readthedocs.io/en/latest/tutorial.html) -- confirmed `Trie` is key-only, `keys(prefix)` returns all keys with given prefix
+- [marisa-trie GitHub](https://github.com/pytries/marisa-trie) -- confirmed API stability
+- [marisa-trie PyPI](https://pypi.org/project/marisa-trie/) -- current version info
+- Source analysis of `folio/graph.py` lines 160-240, 740-773, 1004-1012, 1134-1167, 1250-1287, 1289-1333
diff --git a/.planning/research/FEATURES.md b/.planning/research/FEATURES.md
new file mode 100644
index 0000000..76f0d6b
--- /dev/null
+++ b/.planning/research/FEATURES.md
@@ -0,0 +1,93 @@
+# Feature Landscape: Case-Insensitive Prefix Search
+
+**Domain:** Ontology label prefix search / autocomplete
+**Researched:** 2026-04-07
+
+## Table Stakes
+
+Features that every prefix search / autocomplete implementation handles. Missing any of these would be surprising to callers.
+
+| Feature | Why Expected | Complexity | Notes |
+|---------|--------------|------------|-------|
+| `case_sensitive` parameter | Elasticsearch added this as a query-time flag (issue #61546). Whoosh defaults to case-insensitive. fast-autocomplete docs explicitly tell users to lowercase everything. Every mature search system supports this toggle. | Low | Boolean parameter, default `False`. The ecosystem consensus is overwhelming: case-insensitive is the default behavior for search. |
+| Lowercase normalization at index time | The standard pattern across marisa-trie, fast-autocomplete, pygtrie, and SQLite FTS5: build a parallel normalized index. marisa-trie has no built-in case folding -- you must normalize keys before insertion. | Low | Build a second `marisa_trie.Trie` with `.lower()` keys alongside the existing case-preserving trie. ~18K concepts means negligible memory cost. |
+| Lowercase normalization at query time | Complement to index-time normalization. The query prefix must be lowered with the same function used at index time. | Low | `prefix.lower()` before trie lookup when `case_sensitive=False`. |
+| Reverse mapping from normalized to original | When the trie stores lowercase keys, results must map back to original-case labels to retrieve the correct `OWLClass` objects. fast-autocomplete sidesteps this by requiring callers to lowercase everything; folio-python must preserve original labels. | Low-Med | A `Dict[str, List[str]]` mapping `lowercase_label -> [original_label_1, ...]`. Built once during `_load_folio()`. |
+| Cache normalization | Prefix cache must not store separate entries for "securit", "Securit", "SECURIT" when case-insensitive. The cache key should be the normalized (lowered) prefix. | Low | Normalize cache key to `.lower()` when `case_sensitive=False`. Existing `_prefix_cache` dict keyed by raw prefix string, so this is a minor conditional. |
+| Pure-Python fallback parity | The existing code has both a marisa-trie path and a pure-Python `startswith()` fallback. Both paths must support case-insensitive search identically. | Low | Add `.lower()` to the `startswith()` comparison in the fallback path. |
+
+## Differentiators
+
+Features that go beyond the baseline. Not expected for this scope, but could add value in the future.
+
+| Feature | Value Proposition | Complexity | Notes |
+|---------|-------------------|------------|-------|
+| `str.casefold()` instead of `str.lower()` | Handles Unicode edge cases like German sharp-s (ss/ss), Greek sigma variants, Turkic dotted-I. Python docs recommend `casefold()` for "caseless matching." However, FOLIO ontology labels are English-language legal terms -- no evidence of non-ASCII labels exists in the ~18K concepts. | Low | One-line change from `.lower()` to `.casefold()`. Almost zero risk. **Recommendation: use `casefold()` anyway** -- it costs nothing and is the Python-idiomatic choice for case-insensitive comparison. If FOLIO ever adds non-English labels, it works correctly out of the box. |
+| Unicode NFKD normalization + accent stripping | Decomposes accented characters (e.g., "Munchen" matches "Muenchen") using `unicodedata.normalize('NFKD')` + filtering combining marks. SQLite FTS5's unicode61 tokenizer does this by default. | Medium | Requires building a third normalized trie or a normalization pipeline. Overkill for FOLIO's English-only legal taxonomy. Accent stripping can destroy meaning in languages where accents are phonemically significant. |
+| Locale-aware case folding | Python's `casefold()` follows Unicode's default case folding rules, but some languages have locale-specific rules (e.g., Turkish I/I). ICU-based folding via `icu` or `pyicu` handles these correctly. | High | Adds a C library dependency (libicu). Completely unnecessary for English legal taxonomy labels. |
+| Typo tolerance / fuzzy prefix matching | fast-autocomplete supports Levenshtein distance (`max_cost` parameter). Elasticsearch offers fuzzy prefix queries. Combines prefix matching with edit distance. | High | Already partially covered by `search_by_label()` which uses rapidfuzz for fuzzy matching. Adding fuzzy logic to prefix search would blur the distinction between the two methods. |
+| Result ranking / scoring | fast-autocomplete ranks by configurable count values. Elasticsearch ranks by relevance score. Current `search_by_prefix()` sorts by label length (shortest first), which is a reasonable proxy for relevance in a prefix search context. | Medium | Not needed for the current use case -- callers want all matches for a prefix, sorted by specificity (length). |
+| Synonym expansion during prefix search | fast-autocomplete supports clean synonyms and partial synonyms. FOLIO already stores alternative labels (`alt_label_to_index`) which serve as synonyms. | Medium | Already implemented via alt_label inclusion in the trie. No additional synonym infrastructure needed. |
+| Hidden labels for search only | SKOS defines `hiddenLabel` for terms that should match during search but never display to users (common misspellings, deprecated names). | Medium | Would require extending `OWLClass` model and parser. Not needed for this milestone. |
+
+## Anti-Features
+
+Features to explicitly NOT build for this scope.
+
+| Anti-Feature | Why Avoid | What to Do Instead |
+|--------------|-----------|-------------------|
+| Full-text / substring search | Prefix search is O(prefix length) in a trie. Substring search requires fundamentally different data structures (suffix trees, n-gram indexes, FTS). Mixing concerns would complicate the API and confuse callers about performance characteristics. | Keep `search_by_prefix()` for prefix matching. Use `search_by_label()` (rapidfuzz) for fuzzy/substring-like matching. |
+| Configurable normalization pipeline | Over-engineering. A pluggable normalizer (lowercase -> casefold -> NFKD -> accent strip -> ...) adds API surface and testing burden for zero current benefit. | Hardcode `casefold()` normalization. Revisit if FOLIO adds non-English labels. |
+| Regex-based prefix matching | Python's `re` module supports case-insensitive matching, but regex prefix search cannot use the trie's O(prefix) lookup. It would require scanning all labels -- defeating the purpose of having a trie. | Use the trie for prefix matching, regex for other use cases. |
+| Automatic case detection | Some systems infer case sensitivity from the query (e.g., "if query has uppercase, search case-sensitively"). This is fragile, surprising, and makes behavior depend on input rather than explicit configuration. Whoosh mentions this pattern but it creates unpredictable UX. | Use an explicit `case_sensitive` parameter. Predictable beats clever. |
+| N-gram / edge-ngram indexing | Elasticsearch uses edge-ngram tokenizers for autocomplete at scale. This is a heavyweight indexing strategy for millions of documents. FOLIO has ~18K concepts -- a second trie is sufficient and far simpler. | Parallel lowercase trie. |
+| Removing the existing case-sensitive trie | Backward compatibility. Existing callers may depend on exact-case behavior. | Preserve via `case_sensitive=True` parameter. Both tries coexist. |
+
+## Feature Dependencies
+
+```
+case_sensitive parameter
+ -> lowercase normalization at index time (needs the lowercase trie to exist)
+ -> lowercase normalization at query time (needs to match index normalization)
+ -> reverse mapping normalized -> original (needs to resolve OWLClass from lowercase keys)
+
+cache normalization
+ -> case_sensitive parameter (cache key strategy depends on mode)
+
+pure-Python fallback parity
+ -> case_sensitive parameter (same parameter controls both paths)
+```
+
+All table-stakes features form a single dependency chain rooted in the `case_sensitive` parameter. They should be implemented as one atomic unit, not incrementally.
+
+## MVP Recommendation
+
+**Implement all table-stakes features as a single unit.** They are interdependent and individually incomplete.
+
+Prioritize:
+1. **Parallel lowercase trie** built during `_load_folio()` using `str.casefold()` (not `str.lower()`)
+2. **`case_sensitive=False` default** on `search_by_prefix()`
+3. **Reverse mapping dict** (`casefold_label -> [original_labels]`) for OWLClass resolution
+4. **Cache key normalization** to `casefold()` when case-insensitive
+5. **Pure-Python fallback** updated with same `casefold()` logic
+6. **Tests** covering: lowercase input, UPPERCASE input, mixed case, acronyms (DUI), symbols (M&A), pure-Python fallback path
+
+**Use `casefold()` over `lower()`** -- it is the Python-recommended approach for caseless comparison, costs nothing extra, and future-proofs against non-ASCII labels.
+
+Defer:
+- **Unicode NFKD normalization**: No evidence of accented characters in FOLIO labels. Revisit if FOLIO internationalization happens.
+- **Locale-aware folding**: Would add a C dependency (libicu) for zero current benefit.
+- **Fuzzy prefix search**: Already covered by `search_by_label()` via rapidfuzz.
+
+## Sources
+
+- [marisa-trie documentation](https://marisa-trie.readthedocs.io/en/latest/tutorial.html) -- confirms no built-in case folding; normalization must happen before insertion
+- [fast-autocomplete PyPI](https://pypi.org/project/fast-autocomplete/) -- case-sensitive by default, recommends lowercasing before insertion
+- [Elasticsearch case_insensitive flag (issue #61546)](https://github.com/elastic/elasticsearch/issues/61546) -- added `case_insensitive` parameter to prefix queries
+- [Whoosh documentation](https://whoosh.readthedocs.io/en/latest/recipes.html) -- defaults to case-insensitive via LowercaseFilter in analyzer
+- [pygtrie (Google)](https://github.com/google/pygtrie) -- no built-in case normalization; key normalization is caller's responsibility
+- [SQLite FTS5 documentation](https://www.sqlite.org/fts5.html) -- unicode61 tokenizer provides case folding and optional diacritic removal by default
+- [Python str.casefold() vs str.lower()](https://docs.vultr.com/python/standard-library/str/casefold) -- casefold() handles Unicode edge cases (sharp-s, Greek sigma)
+- [OpenSearch Autocomplete documentation](https://docs.opensearch.org/latest/search-plugins/searching-data/autocomplete/) -- edge-ngram and completion suggester approaches
+- [Python unicodedata.normalize](https://docs.python.org/3/library/unicodedata.html) -- NFKD decomposition for accent stripping
+- [SKOS Reference (W3C)](https://www.w3.org/TR/skos-reference/) -- hiddenLabel for search-only terms
diff --git a/.planning/research/PITFALLS.md b/.planning/research/PITFALLS.md
new file mode 100644
index 0000000..156aba7
--- /dev/null
+++ b/.planning/research/PITFALLS.md
@@ -0,0 +1,226 @@
+# Domain Pitfalls
+
+**Domain:** Case-insensitive prefix search on a parallel lowercase marisa-trie (folio-python)
+**Researched:** 2026-04-07
+
+## Critical Pitfalls
+
+Mistakes that cause incorrect results, silent data loss, or require rewrites.
+
+### Pitfall 1: Lowercase Label Collision Produces Duplicate OWLClass Results
+
+**What goes wrong:** Multiple original labels map to the same lowercase key. For example, if both `"DUI"` (an all-caps acronym in `alt_label_to_index`) and `"Dui"` (hypothetical title-case variant in `label_to_index`) both lowercase to `"dui"`, the lowercase trie contains only one key `"dui"`, but the reverse lookup dictionary `lowercase_to_original_labels` must map it to *both* originals. Each original then resolves to its own index list via `label_to_index` or `alt_label_to_index`. If the same OWLClass appears under both labels, `iri_list` will contain that index twice and the caller gets duplicate OWLClass objects in the result.
+
+**Why it happens:** The current `search_by_prefix()` already has no deduplication -- it extends `iri_list` from both `label_to_index` and `alt_label_to_index` without checking for duplicates (lines 1322-1326). Today this is masked because case-sensitive keys rarely collide. Once lowercase keys are introduced, collisions become common.
+
+**Real FOLIO examples from the issue:**
+- The maintainer (@mjbommar) explicitly flagged `"turkey" vs "Turkey"` and `"may" vs "May"` as cases where the same lowercase form maps to semantically different concepts (the country vs the bird, the month vs the modal verb). These are not duplicates -- they are *distinct concepts that share a lowercase form*.
+- `"US+GA"` (Georgia the U.S. state) and a hypothetical `"Georgia"` (the country) could share the prefix `"georgia"`.
+
+**Consequences:** Callers receive the same OWLClass multiple times in results, inflating result counts and breaking downstream logic that assumes unique results (e.g., folio-mapper selecting top-N candidates).
+
+**Prevention:**
+1. Add IRI-based deduplication in `search_by_prefix()` using a `seen_iris: set` -- exactly as `search_by_label()` already does at line 1401-1410.
+2. Build the `lowercase_to_original_labels` mapping as `Dict[str, List[str]]` (one lowercase key maps to multiple original labels), then look up ALL originals and extend `iri_list` from each.
+3. Deduplicate `iri_list` while preserving order (use `dict.fromkeys(iri_list)` or a seen-set loop).
+
+**Detection:** Write a test that searches for a prefix known to match both a `label` and an `alt_label` of the *same* OWLClass, and assert `len(results) == len(set(r.iri for r in results))`.
+
+**Phase:** Must be addressed in the core implementation phase, not deferred to testing.
+
+---
+
+### Pitfall 2: Reverse Mapping From Lowercase Keys Back to Original Labels is Incomplete
+
+**What goes wrong:** The lowercase trie finds matching lowercase keys, but you still need to look up the original-case labels to resolve indices from `label_to_index` and `alt_label_to_index`. If the reverse mapping (`lowercase -> [original_labels]`) is built incorrectly -- for instance, by overwriting instead of appending when two originals share a lowercase form -- some original labels are silently lost, and their OWLClass objects never appear in results.
+
+**Why it happens:** The natural instinct is `lower_to_original[label.lower()] = label`, which overwrites. The correct structure is `lower_to_original[label.lower()].append(label)` using a `defaultdict(list)` or equivalent.
+
+**Consequences:** Silent result loss -- the exact bug this feature is meant to fix, just in a different form.
+
+**Prevention:**
+1. Use `defaultdict(list)` for the reverse mapping.
+2. Populate it from *both* `label_to_index.keys()` and `alt_label_to_index.keys()`.
+3. Write a test asserting that `len(lower_to_original_labels)` is <= total unique labels (proving many-to-one mapping works), AND that resolving any lowercase key back through the mapping reaches all the original labels.
+
+**Detection:** After building the mapping, assert `sum(len(v) for v in lower_to_original.values()) == len(all_labels)`. If less, labels were dropped.
+
+**Phase:** Core implementation phase -- this is the data structure design, not an afterthought.
+
+---
+
+### Pitfall 3: Cache Serves Stale or Split Results When Mixing Case Modes
+
+**What goes wrong:** The current `_prefix_cache` is a plain `Dict[str, List[OWLClass]]` keyed by the raw prefix string (line 1300). If `case_sensitive` becomes a parameter:
+- `search_by_prefix("Securit", case_sensitive=True)` caches under key `"Securit"` with 39 results.
+- `search_by_prefix("Securit", case_sensitive=False)` hits the *same cache key* `"Securit"` and returns the case-sensitive results (39 instead of potentially more).
+- Conversely, `search_by_prefix("securit", case_sensitive=False)` caches under `"securit"`, and a later `search_by_prefix("securit", case_sensitive=True)` returns the case-insensitive results (wrong -- case-sensitive search for `"securit"` should return 0).
+
+**Why it happens:** The cache key does not encode the `case_sensitive` flag.
+
+**Consequences:** Incorrect search results that depend on call order -- a heisenbug that's nearly impossible to reproduce reliably in testing but causes production failures.
+
+**Prevention:** Two options (pick one):
+1. **Separate caches:** `_prefix_cache_cs` and `_prefix_cache_ci` -- simple, no ambiguity.
+2. **Compound cache key:** `_prefix_cache[(prefix, case_sensitive)]` -- single dict, but requires changing the key type.
+
+Option 1 is cleaner because case-insensitive cache can normalize the prefix to lowercase before lookup (`_prefix_cache_ci[prefix.lower()]`), ensuring `"Securit"` and `"securit"` share one cache entry when case-insensitive.
+
+**Detection:** Write a test that calls `search_by_prefix("Securit", case_sensitive=True)` then `search_by_prefix("Securit", case_sensitive=False)` and asserts the second call returns a superset of the first.
+
+**Phase:** Core implementation phase -- cache design must match the API contract from the start.
+
+---
+
+### Pitfall 4: `refresh()` Does Not Clear the New Lowercase Trie or Cache
+
+**What goes wrong:** The existing `refresh()` method (lines 1257-1266) clears `label_to_index`, `alt_label_to_index`, `class_edges`, and `triples`, but it does NOT clear `_prefix_cache` or `_label_trie`. After `refresh()`, the trie and cache contain stale entries pointing to old indices that no longer exist in `self.classes`. This is an *existing bug* that will be inherited by the new lowercase trie and its reverse mapping.
+
+**Why it happens:** `refresh()` was written before the trie/cache were added, or the clearing was simply missed.
+
+**Consequences:** After `refresh()`, prefix searches return stale results or raise `IndexError` when materializing `self[index]` for an index that no longer exists.
+
+**Prevention:**
+1. Fix `refresh()` to also clear `_label_trie`, the new `_lowercase_label_trie`, `_prefix_cache` (both case-sensitive and case-insensitive variants), and `_lower_to_original_labels`.
+2. Alternatively, since `refresh()` calls `parse_owl()` which rebuilds the trie at lines 1004-1012, the trie itself gets rebuilt -- but the *cache* is definitely stale and must be cleared.
+3. Add a `_clear_search_indices()` helper that `refresh()` and `__init__` both call.
+
+**Detection:** Write a test: call `search_by_prefix("Mich")`, then `refresh()`, then `search_by_prefix("Mich")` again, and assert the second result is fresh (same content but re-materialized from new indices).
+
+**Phase:** Should be fixed as part of the implementation phase since you are already modifying the search infrastructure.
+
+---
+
+## Moderate Pitfalls
+
+### Pitfall 5: Using `str.lower()` Instead of `str.casefold()` for Normalization
+
+**What goes wrong:** Python's `str.lower()` is locale-unaware and does not handle certain Unicode case mappings. The classic example is the German Eszett: `"STRASSE".lower()` produces `"strasse"`, but `"Stra\u00dfe".casefold()` produces `"strasse"` while `"Stra\u00dfe".lower()` produces `"stra\u00dfe"` -- these do not match.
+
+**Why it matters for FOLIO:** The PROJECT.md states "no evidence of non-ASCII labels in FOLIO" and declares Unicode normalization beyond `.lower()` as out of scope. This is a *reasonable scoping decision* for now, because FOLIO labels are English legal terms. However, FOLIO includes labels for international jurisdictions (Denmark/DK, Georgia), and future ontology versions may add non-ASCII labels (e.g., German legal terms like "Gesch\u00e4ftsf\u00fchrer" or French "Soci\u00e9t\u00e9").
+
+**Prevention:**
+1. Use `str.casefold()` instead of `str.lower()` -- it costs nothing extra and is the Python-recommended approach for case-insensitive comparison.
+2. Both the trie keys AND the query prefix must use the same normalization (`prefix.casefold()` and `label.casefold()`).
+3. Document the normalization choice so future contributors know what to expect.
+
+**Detection:** `"stra\u00dfe".casefold() == "strasse".casefold()` returns `True`; `"stra\u00dfe".lower() == "strasse".lower()` returns `False`.
+
+**Note:** The maintainer's comment about "turkey vs Turkey" is about *semantic* distinction (country vs bird), NOT about Unicode edge cases. `str.casefold()` would not help distinguish those -- that requires the `case_sensitive=True` parameter.
+
+---
+
+### Pitfall 6: Pure-Python Fallback Path Diverges From Trie Path
+
+**What goes wrong:** The existing code has two code paths: one using `marisa_trie` (lines 1304-1309) and one using pure Python list comprehension (lines 1311-1320). Both must be updated for case-insensitive search. If only the trie path is updated, users without `marisa_trie` installed get different (case-sensitive) behavior -- a silent behavioral divergence.
+
+**Why it happens:** The fallback path is easy to forget because it is only exercised when `marisa_trie` is not installed, and the test suite almost certainly runs with it installed.
+
+**Consequences:** Bug reports from users who install `folio-python` without the search extras, or in constrained environments where C extensions cannot be compiled.
+
+**Prevention:**
+1. Update *both* paths in the same commit/PR.
+2. The pure-Python fallback for case-insensitive search is: `[label for label in all_labels if label.lower().startswith(prefix.lower())]` (or `.casefold()`).
+3. Add a test that monkeypatches `marisa_trie` to `None` and verifies case-insensitive search still works.
+
+**Detection:** In tests, use `@pytest.fixture` to temporarily set the module-level `marisa_trie` to `None` and run the same search assertions.
+
+**Phase:** Core implementation phase -- both paths must be updated simultaneously.
+
+---
+
+### Pitfall 7: The `case_sensitive=False` Default Silently Changes Existing Behavior
+
+**What goes wrong:** If `case_sensitive` defaults to `False`, existing callers who pass title-cased prefixes (e.g., `search_by_prefix("Mich")`) will now receive a *superset* of previous results -- their existing matches plus any additional matches from other case variants. This is the intended behavior per PROJECT.md ("returns a superset"), but it can break tests or downstream code that asserts exact result counts or exact ordering.
+
+**Why it happens:** A default-False parameter is an API-compatible change in *contract* (superset of old results), but not in *exact output* (more results, possibly different order).
+
+**Consequences:**
+- The existing test `test_search_prefix` (line 256-259) searches for `"Mich"` and asserts the first result's label is `"Michigan"`. This might still pass if "Michigan" remains first in sort order, but the result count changes.
+- Benchmark test `test_benchmark_search_prefix` (line 455-458) measures performance; more results may change timing characteristics.
+
+**Prevention:**
+1. Verify the existing test still passes with the new default by running the full test suite after implementation.
+2. If the superset guarantee is important, add an explicit test: `assert set(case_insensitive_results) >= set(case_sensitive_results)`.
+3. Consider whether the sorted-by-length ordering (line 1306-1308) still produces intuitive results when case variants are merged.
+
+**Detection:** Run `pytest tests/test_folio.py::test_search_prefix -v` before and after the change.
+
+**Phase:** Testing phase, but must be anticipated during implementation design.
+
+---
+
+### Pitfall 8: Trie Key Length Filter Drops Short Acronyms
+
+**What goes wrong:** The trie building code (line 1010) filters out labels shorter than `MIN_PREFIX_LENGTH` (which is 3, per line 125). This means two-character labels like `"IP"`, `"DK"`, or `"EU"` are never inserted into the trie and cannot be found by prefix search. The same filter will apply to the lowercase trie.
+
+**Why it matters:** The issue explicitly calls out `"ip"` as a case where case-insensitive search should match `"IP Licensing"`. The prefix `"ip"` is only 2 characters, so `search_by_prefix("ip")` would fail regardless of case -- not because of case sensitivity, but because of the length filter. Users will think case-insensitive search is broken when it is actually a different issue.
+
+**Consequences:** Confusion and bug reports. The case-insensitive feature appears not to work for short prefixes.
+
+**Prevention:**
+1. Document in the `search_by_prefix()` docstring that prefixes shorter than `MIN_PREFIX_LENGTH` (3) may not match.
+2. Consider whether `MIN_PREFIX_LENGTH` should be lowered to 2 for the lowercase trie (this is a separate decision from case-insensitivity).
+3. Ensure the new tests do not test 2-character prefixes and then blame case-insensitivity for the failure.
+
+**Detection:** `search_by_prefix("IP")` returns `[]` even today. Verify this is documented.
+
+**Phase:** Scoping/design phase -- decide whether to address this or explicitly mark out of scope.
+
+---
+
+## Minor Pitfalls
+
+### Pitfall 9: The Turkish I Problem is Irrelevant but Will Be Raised
+
+**What goes wrong:** Someone reviewing the code will point out that `"INFO".lower()` produces `"info"` in Python (correct) but would produce `"i\u0307nfo"` in a Turkish locale. In Python 3, `str.lower()` and `str.casefold()` are NOT locale-dependent -- they always use Unicode default case mappings. The Turkish I problem affects C's `tolower()` and Java's `String.toLowerCase(Locale)`, but NOT Python 3 strings.
+
+**Why it matters:** This is a non-issue for Python, but it will waste review time if not preemptively addressed.
+
+**Prevention:** Add a code comment: `# Python 3's str.lower()/casefold() uses Unicode default mapping, not locale-dependent. Turkish I is not an issue.`
+
+**Detection:** `"\u0130".casefold() == "i\u0307"` in Python 3 (always, regardless of locale).
+
+---
+
+### Pitfall 10: Memory Doubling Concern is a Red Herring
+
+**What goes wrong:** A reviewer flags that building a second marisa-trie doubles memory usage for the trie. Since the project has approximately 18K concepts and `marisa-trie` is a compressed LOUDS-based structure, the entire trie fits in hundreds of KB. The reverse mapping `Dict[str, List[str]]` is similarly small.
+
+**Why it matters:** This is a non-issue but will be raised.
+
+**Prevention:** The maintainer already approved this approach in the issue comments: "It's cheap because the data structure is so cheap to keep in memory and efficient for lookup."
+
+---
+
+### Pitfall 11: Labels With Special Characters Lowercase Identically
+
+**What goes wrong:** Labels like `"M&A Practice Components"` contain special characters. `"M&A".lower()` produces `"m&a"`, which is fine. But consider `"M&A"` vs `"M&a"` vs `"m&A"` -- all lowercase to `"m&a"`. If these are distinct labels in the ontology (unlikely but possible), they share one lowercase trie entry. This is by design, but worth being aware of.
+
+**Prevention:** The reverse mapping handles this naturally if built as `Dict[str, List[str]]`. No special handling needed for `&`, `-`, `.`, or other non-alpha characters since `.lower()` and `.casefold()` pass them through unchanged.
+
+---
+
+## Phase-Specific Warnings
+
+| Phase Topic | Likely Pitfall | Mitigation |
+|-------------|---------------|------------|
+| Data structure design | Pitfall 2 (reverse mapping) | Use `defaultdict(list)`, populate from both label dicts |
+| Trie building | Pitfall 8 (MIN_PREFIX_LENGTH) | Document the 3-char minimum, decide scope |
+| search_by_prefix() rewrite | Pitfall 1 (duplicates), Pitfall 3 (cache) | Add IRI dedup, separate caches per mode |
+| Pure-Python fallback | Pitfall 6 (divergence) | Update both paths simultaneously |
+| refresh() integration | Pitfall 4 (stale cache) | Clear all new data structures in refresh() |
+| Test writing | Pitfall 7 (default change) | Test superset property, not exact counts |
+| Normalization choice | Pitfall 5 (lower vs casefold) | Use casefold() everywhere, consistently |
+| Code review | Pitfall 9 (Turkish I), Pitfall 10 (memory) | Preemptive comments addressing non-issues |
+
+## Sources
+
+- [marisa-trie tutorial and API docs](https://marisa-trie.readthedocs.io/en/latest/tutorial.html) - Trie key behavior, duplicate handling
+- [marisa-trie GitHub](https://github.com/pytries/marisa-trie) - Source code and issue tracker
+- [Python `str.casefold()` vs `str.lower()`](https://dev.to/bowmanjd/case-insensitive-string-comparison-in-python-using-casefold-not-lower-5fpi) - Best practice for case-insensitive comparison
+- [Python bug tracker: Turkish I](https://bugs.python.org/issue34723) - `lower()` on Turkish I returns 2-char string
+- [GitHub Issue #15](https://github.com/alea-institute/folio-python/issues/15) - Original feature request with edge cases
+- [Maintainer comment on Issue #15](https://github.com/alea-institute/folio-python/issues/15#issuecomment) - Approval of Option 1, flags "turkey vs Turkey" and "may vs May"
+- [hat-trie case-insensitive prefix search discussion](https://github.com/Tessil/hat-trie/issues/7) - General trie case-insensitivity patterns
+- Current source code analysis: `folio/graph.py` lines 125, 200-218, 740-773, 1004-1012, 1250-1333
diff --git a/.planning/research/STACK.md b/.planning/research/STACK.md
new file mode 100644
index 0000000..d22c9d8
--- /dev/null
+++ b/.planning/research/STACK.md
@@ -0,0 +1,102 @@
+# Technology Stack
+
+**Project:** folio-python — case-insensitive prefix search
+**Researched:** 2026-04-07
+**Confidence:** HIGH (all claims verified from source code)
+
+## Current Stack
+
+### Core Dependencies (required)
+
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| Python | >=3.10, <4 | Runtime; `str.casefold()` available since 3.0 |
+| pydantic | >=2.8.2 | OWLClass model validation |
+| lxml | >=5.2.2 | OWL/XML parsing |
+
+### Search Dependencies (optional extras: `folio-python[search]`)
+
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| marisa-trie | >=1.2.0, <2 | Compressed prefix trie for `search_by_prefix()` |
+| rapidfuzz | >=3.10.0, <4 | Fuzzy label matching for `search_by_label()` |
+| alea-llm-client | >=0.1.1 | LLM-assisted search |
+
+## marisa-trie API for This Feature
+
+The feature uses exactly two marisa-trie operations — both already in use in the codebase.
+
+### Construction (`graph.py:1005-1012`)
+
+```python
+self._label_trie = marisa_trie.Trie(all_labels)
+```
+
+`marisa_trie.Trie(iterable)` accepts any iterable of `str`. To build the parallel lowercase trie, pass the same label list with `casefold()` applied:
+
+```python
+self._lowercase_label_trie = marisa_trie.Trie(
+ label.casefold() for label in all_labels
+)
+```
+
+### Prefix lookup (`graph.py:1306-1309`)
+
+```python
+keys = sorted(self._label_trie.keys(prefix), key=len)
+```
+
+`trie.keys(prefix: str) -> List[str]` returns all stored strings that start with `prefix`. For the lowercase trie, pass `prefix.casefold()` as the query:
+
+```python
+keys = sorted(self._lowercase_label_trie.keys(prefix.casefold()), key=len)
+```
+
+No other marisa-trie API surface is needed.
+
+## No New Dependencies Required
+
+The parallel trie approach uses only constructs already present in the codebase:
+
+- `marisa_trie.Trie` — already imported and guarded at `graph.py:138-142`
+- `str.casefold()` — Python stdlib, no import
+- `dict` bridge (`_lowercase_to_original: Dict[str, List[str]]`) — plain Python
+
+The pure-Python fallback path (`graph.py:1312-1320`) requires only `str.casefold()` and `str.startswith()` — also no new imports.
+
+## Memory and Performance
+
+| Concern | Assessment |
+|---------|------------|
+| Second trie size | MARISA compression on ~18K short label strings produces a trie of roughly 1-2 MB. A second trie over the same labels (casefolded) is the same order of magnitude — negligible. |
+| Build time | Trie construction runs once during `_load_folio()`. Adding a second `marisa_trie.Trie(...)` call adds milliseconds. |
+| Lookup performance | `trie.keys(prefix)` is O(|prefix| + |results|) — identical for both tries. |
+| Cache overhead | Two separate `_prefix_cache` dicts (one per `case_sensitive` flag value). At ~18K concepts, worst-case cache size is still small. Alternatively, normalize cache key to `(prefix.casefold(), case_sensitive)` tuple to share entries across case variants when `case_sensitive=False`. |
+| Bridge dict | `_lowercase_to_original: Dict[str, List[str]]` maps each casefolded label back to its original-case form(s). Required because `trie.keys()` on the lowercase trie returns casefolded keys; those must resolve to the original `label_to_index` / `alt_label_to_index` lookups. At 18K entries this dict is trivially small. |
+
+## `casefold()` vs `lower()`
+
+Use `str.casefold()` throughout — not `str.lower()`.
+
+- `casefold()` is the Python-idiomatic choice for case-insensitive comparison (PEP 3131, Python docs).
+- It handles Unicode edge cases `lower()` misses (e.g., German `"ß".casefold() == "ss"`, not `"ß"`).
+- FOLIO labels are currently ASCII/Latin-1, so the difference is moot today — but `casefold()` is correct-by-default for future robustness.
+- Consistent use of the same normalization function at build time and query time is what matters most; `casefold()` satisfies this.
+
+## Implementation Touchpoints
+
+| Location | Change |
+|----------|--------|
+| `graph.py:1004-1012` | Add `self._lowercase_label_trie` and `self._lowercase_to_original` dict alongside existing trie build |
+| `graph.py:1289` | Add `case_sensitive: bool = False` parameter to `search_by_prefix()` |
+| `graph.py:1300-1330` | Branch on `case_sensitive`; use lowercase trie + bridge dict when `False`; normalize cache key |
+| Pure-Python fallback (`graph.py:1312-1320`) | Add `label.casefold().startswith(prefix.casefold())` branch |
+
+## Alternatives Considered
+
+| Category | Recommended | Alternative | Why Not |
+|----------|-------------|-------------|---------|
+| Case normalization | `casefold()` | `lower()` | `lower()` misses Unicode edge cases; `casefold()` is the stdlib-blessed choice |
+| Architecture | Parallel trie + bridge dict | Single trie with post-filter | Post-filter forfeits O(prefix) trie advantage; scans all keys |
+| Architecture | Parallel trie + bridge dict | Case-normalize labels in-place | Destroys original-case labels needed for display and downstream lookups |
+| Cache design | Per-flag cache or tuple key | Single shared cache | Without normalization, `"securit"` and `"Securit"` would produce duplicate entries |
diff --git a/.planning/research/SUMMARY.md b/.planning/research/SUMMARY.md
new file mode 100644
index 0000000..5124dcd
--- /dev/null
+++ b/.planning/research/SUMMARY.md
@@ -0,0 +1,57 @@
+# Research Summary: Case-Insensitive Prefix Search
+
+**Synthesized:** 2026-04-07
+**Sources:** STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md
+**Confidence:** HIGH — all claims verified against `graph.py` source with specific line numbers
+
+## Executive Summary
+
+All four research dimensions converge on the same architecture: a parallel lowercase `marisa-trie` alongside the existing case-sensitive trie, bridged back to original-case label dicts via a `Dict[str, List[str]]` reverse mapping. No new dependencies required. The implementation touches exactly four locations in `graph.py`.
+
+## Key Recommendations
+
+### Stack
+- **`marisa_trie.Trie`** — second instance adds ~1-2 MB RAM, negligible for ~18K labels
+- **`str.casefold()`** — use everywhere instead of `str.lower()`; handles Unicode edge cases (German sharp-s); Python 3 is not locale-dependent
+- **`Dict[str, List[str]]` bridge dict** — plain Python `defaultdict(list)`; maps `casefold(label)` back to list of original-case labels
+
+### Architecture — "parallel index with bridge dict"
+```
+case_sensitive=False
+ -> _lowercase_label_trie.keys(prefix.casefold()) # ["securities fraud", ...]
+ -> _lowercase_to_original["securities fraud"] # ["Securities Fraud"]
+ -> label_to_index["Securities Fraud"] # [42]
+ -> self.classes[42] # OWLClass
+```
+One resolution path, two entry points. The existing `label_to_index` / `alt_label_to_index` dicts remain source of truth.
+
+### Table Stakes (all interdependent — ship as one unit)
+- `case_sensitive: bool = False` parameter on `search_by_prefix()`
+- Parallel lowercase trie (`_lowercase_label_trie`) built in `parse_owl()`
+- Reverse mapping dict (`_lowercase_to_original`) built with `defaultdict(list)`
+- Separate case-insensitive cache (`_ci_prefix_cache`) keyed by `prefix.casefold()`
+- Pure-Python fallback updated with same `casefold()` logic
+- IRI-based deduplication using a `seen` set on integer indices
+
+### Defer (out of scope)
+- NFKD normalization, locale-aware folding, fuzzy prefix matching
+
+## Critical Pitfalls
+
+1. **Duplicate OWLClass results** — "DUI" and "Dui" both fold to "dui"; bridge dict must be `List[str]`, result assembly must deduplicate by index
+2. **Scalar assignment drops labels** — `lower_to_original[key] = label` overwrites; must use `defaultdict(list).append()`
+3. **Single cache produces heisenbug** — use two separate caches (case-sensitive and case-insensitive)
+4. **`refresh()` leaves structures stale** — pre-existing bug; fix by resetting both caches at top of trie-building block in `parse_owl()`
+5. **Pure-Python fallback divergence** — must update both paths simultaneously
+
+## Scoping Decisions Needed
+
+- **`MIN_PREFIX_LENGTH = 3`** (line 125) filters out 2-char queries like "IP". Issue #15 mentions "ip" as expected use case. Lower to 2, or document the limitation?
+- **Pre-existing `_prefix_cache` staleness in `refresh()`** — fix in same PR (recommended) or separately?
+
+## Roadmap Implications
+
+4 natural phases: (1) data structure declarations, (2) index building in `parse_owl()`, (3) search logic + fallback, (4) tests. Phases 1-2 are zero-behavioral-change. Phase 3 is the only behavioral change.
+
+---
+*Synthesized: 2026-04-07*
diff --git a/folio/graph.py b/folio/graph.py
index 5cce2b8..7c93f6e 100644
--- a/folio/graph.py
+++ b/folio/graph.py
@@ -230,7 +230,10 @@ def __init__(
self.class_edges: Dict[str, List[str]] = {}
self._cached_triples: Tuple[Tuple[str, str, str], ...] = ()
self._label_trie: Optional[marisa_trie.Trie] = None
+ self._lowercase_label_trie: Optional[marisa_trie.Trie] = None
+ self._lowercase_to_original: Dict[str, List[str]] = {}
self._prefix_cache: Dict[str, List[OWLClass]] = {}
+ self._ci_prefix_cache: Dict[str, List[OWLClass]] = {}
self.triples: List[Tuple[str, str, str]] = []
# load the ontology
@@ -1029,6 +1032,10 @@ def parse_owl(self, buffer: str) -> None:
# freeze triple tuples
self._cached_triples = tuple(self.triples)
+ # clear prefix caches (fixes staleness on refresh())
+ self._prefix_cache = {}
+ self._ci_prefix_cache = {}
+
# now create the Trie for the labels in label_to_index and alt_label_to_index
if marisa_trie is not None:
all_labels = [
@@ -1039,6 +1046,17 @@ def parse_owl(self, buffer: str) -> None:
]
self._label_trie = marisa_trie.Trie(all_labels)
+ # build lowercase-to-original bridge dict and lowercase trie
+ self._lowercase_to_original = {}
+ for label in all_labels:
+ folded = label.casefold()
+ if folded not in self._lowercase_to_original:
+ self._lowercase_to_original[folded] = []
+ self._lowercase_to_original[folded].append(label)
+ self._lowercase_label_trie = marisa_trie.Trie(
+ list(self._lowercase_to_original.keys())
+ )
+
def get_subgraph(
self, iri: str, max_depth: int = DEFAULT_MAX_DEPTH
) -> List[OWLClass]:
@@ -1314,29 +1332,38 @@ def refresh(self) -> None:
end_time = time.time()
LOGGER.info("Parsed FOLIO ontology in %.2f seconds", end_time - start_time)
- def search_by_prefix(self, prefix: str) -> List[OWLClass]:
+ def search_by_prefix(
+ self, prefix: str, case_sensitive: bool = False
+ ) -> List[OWLClass]:
"""
- Search for IRIs by prefix.
+ Search for OWL classes by label prefix.
Args:
prefix (str): The prefix to search for.
+ case_sensitive (bool): If True, match original-case labels exactly.
+ If False (default), match case-insensitively via a parallel
+ lowercase trie.
Returns:
- List[OWLClass]: The list of OWL classes with IRIs that start with the prefix.
+ List[OWLClass]: The list of OWL classes whose labels start with
+ the prefix, sorted by label length ascending.
"""
- # check for cache
+ if case_sensitive:
+ return self._search_by_prefix_sensitive(prefix)
+ return self._search_by_prefix_insensitive(prefix)
+
+ def _search_by_prefix_sensitive(self, prefix: str) -> List[OWLClass]:
+ """Case-sensitive prefix search (original behavior)."""
if prefix in self._prefix_cache:
return self._prefix_cache[prefix]
- # search in trie
+ # sort: primary-label keys first (False < True), then by length
if marisa_trie is not None:
- # return in sorted by length ascending list
keys = sorted(
- self._label_trie.keys(prefix),
- key=len,
+ self._label_trie.keys(prefix), # type: ignore[union-attr]
+ key=lambda k: (k not in self.label_to_index, len(k)),
)
else:
- # search with pure python
keys = sorted(
[
label
@@ -1344,20 +1371,76 @@ def search_by_prefix(self, prefix: str) -> List[OWLClass]:
+ list(self.alt_label_to_index.keys())
if label.startswith(prefix)
],
- key=len,
+ key=lambda k: (k not in self.label_to_index, len(k)),
)
- # get the list of IRIs
- iri_list = []
+ # deduplicate by class index, label_to_index checked before alt_label_to_index
+ seen: set = set()
+ iri_list: list = []
for key in keys:
- iri_list.extend(self.label_to_index.get(key, []))
- iri_list.extend(self.alt_label_to_index.get(key, []))
+ for idx in self.label_to_index.get(key, []): # type: ignore[arg-type]
+ if idx not in seen:
+ seen.add(idx)
+ iri_list.append(idx)
+ for idx in self.alt_label_to_index.get(key, []): # type: ignore[arg-type]
+ if idx not in seen:
+ seen.add(idx)
+ iri_list.append(idx)
- # materialize and cache
classes = [self[index] for index in iri_list]
- self._prefix_cache[prefix] = classes
+ self._prefix_cache[prefix] = classes # type: ignore[assignment]
+ return classes
+
+ def _search_by_prefix_insensitive(self, prefix: str) -> List[OWLClass]:
+ """Case-insensitive prefix search via parallel lowercase trie."""
+ folded = prefix.casefold()
+
+ if folded in self._ci_prefix_cache:
+ return self._ci_prefix_cache[folded]
- # return the classes
+ if marisa_trie is not None and self._lowercase_label_trie is not None:
+ lowercase_keys = sorted(
+ self._lowercase_label_trie.keys(folded), # type: ignore[union-attr]
+ key=len,
+ )
+ # resolve lowercase keys back to original-case labels;
+ # sort: primary-label keys first, then by length
+ original_keys = sorted(
+ [
+ orig
+ for lk in lowercase_keys
+ for orig in self._lowercase_to_original.get(lk, [])
+ ],
+ key=lambda k: (k not in self.label_to_index, len(k)),
+ )
+ else:
+ # pure-Python fallback: case-insensitive prefix match
+ # sort: primary-label keys first, then by length
+ original_keys = sorted(
+ [
+ label
+ for label in list(self.label_to_index.keys())
+ + list(self.alt_label_to_index.keys())
+ if label.casefold().startswith(folded)
+ ],
+ key=lambda k: (k not in self.label_to_index, len(k)),
+ )
+
+ # resolve to OWLClass with deduplication by index
+ seen: set = set()
+ iri_list: list = []
+ for key in original_keys:
+ for idx in self.label_to_index.get(key, []): # type: ignore[arg-type]
+ if idx not in seen:
+ seen.add(idx)
+ iri_list.append(idx)
+ for idx in self.alt_label_to_index.get(key, []): # type: ignore[arg-type]
+ if idx not in seen:
+ seen.add(idx)
+ iri_list.append(idx)
+
+ classes = [self[index] for index in iri_list]
+ self._ci_prefix_cache[folded] = classes # type: ignore[assignment]
return classes
@staticmethod
diff --git a/tests/test_folio.py b/tests/test_folio.py
index 648e508..328f332 100644
--- a/tests/test_folio.py
+++ b/tests/test_folio.py
@@ -5,6 +5,7 @@
import pytest
# project imports
+import folio.graph
from folio import FOLIO, FOLIOTypes, FOLIO_TYPE_IRIS, OWLClass
@@ -254,12 +255,96 @@ def test_all_formatters(folio_graph):
def test_search_prefix(folio_graph):
- for c in folio_graph.search_by_prefix("Mich"):
+ """Original test: case-sensitive prefix search preserves prior behavior."""
+ for c in folio_graph.search_by_prefix("Mich", case_sensitive=True):
assert c.label == "Michigan"
assert "US+MI" in c.alternative_labels
break
+def test_search_prefix_case_insensitive(folio_graph):
+ """Case-insensitive prefix search returns results for lowercase input."""
+ results = folio_graph.search_by_prefix("securit")
+ assert len(results) > 0
+ labels = [c.label for c in results]
+ assert any("Securit" in label for label in labels)
+
+
+def test_search_prefix_case_insensitive_acronym(folio_graph):
+ """Case-insensitive prefix search handles acronyms like DUI."""
+ results = folio_graph.search_by_prefix("dui")
+ assert len(results) > 0
+ labels = [c.label for c in results]
+ assert any("Driving Under the Influence" in label for label in labels)
+
+
+def test_search_prefix_case_sensitive_preserves_behavior(folio_graph):
+ """case_sensitive=True: lowercase input returns nothing, title-case works."""
+ assert len(folio_graph.search_by_prefix("securit", case_sensitive=True)) == 0
+ assert len(folio_graph.search_by_prefix("Securit", case_sensitive=True)) > 0
+
+
+def test_search_prefix_no_duplicates(folio_graph):
+ """Case-insensitive results contain no duplicate OWLClass objects."""
+ results = folio_graph.search_by_prefix("mich")
+ iris = [c.iri for c in results]
+ assert len(iris) == len(set(iris)), f"Duplicate IRIs found: {iris}"
+
+
+def test_search_prefix_case_sensitive_no_duplicates(folio_graph):
+ """Case-sensitive search returns no duplicate OWLClass entries."""
+ results = folio_graph.search_by_prefix("Mich", case_sensitive=True)
+ iris = [c.iri for c in results]
+ assert len(iris) == len(set(iris)), (
+ f"Duplicate IRIs in case-sensitive results: {iris}"
+ )
+
+
+def test_search_prefix_primary_label_ranks_first(folio_graph):
+ """Primary-label matches rank before alt-label matches for same prefix."""
+ # Use "Mich" where Michigan (primary label, 8 chars) should beat any
+ # alt-label-only match. Verify it appears before any alt-label-only result.
+ results = folio_graph.search_by_prefix("Mich", case_sensitive=True)
+ if not results:
+ return
+ # Michigan is a short primary label -- it should be first
+ assert results[0].label == "Michigan", (
+ f"Expected Michigan first, got {results[0].label!r}"
+ )
+ # All results should have no duplicate IRIs (dedup working)
+ iris = [c.iri for c in results]
+ assert len(iris) == len(set(iris))
+
+ # Case-insensitive path: "mich" should also put Michigan near top
+ results_ci = folio_graph.search_by_prefix("mich")
+ labels_ci = [c.label for c in results_ci]
+ if "Michigan" in labels_ci:
+ mi_idx = labels_ci.index("Michigan")
+ assert mi_idx < 5, (
+ f"Michigan at index {mi_idx} in CI results, expected near top"
+ )
+
+
+def test_search_prefix_fallback_parity(folio_graph, monkeypatch):
+ """Pure-Python fallback produces same IRI set as trie path."""
+ # get trie results first (uses marisa_trie path)
+ trie_results = folio_graph.search_by_prefix("securit")
+ trie_iris = sorted(c.iri for c in trie_results)
+
+ # clear cache so fallback path runs fresh
+ folio_graph._ci_prefix_cache = {}
+
+ # disable marisa_trie at module level to trigger pure-Python fallback
+ monkeypatch.setattr(folio.graph, "marisa_trie", None)
+
+ fallback_results = folio_graph.search_by_prefix("securit")
+ fallback_iris = sorted(c.iri for c in fallback_results)
+
+ assert trie_iris == fallback_iris, (
+ f"Trie ({len(trie_iris)}) and fallback ({len(fallback_iris)}) results differ"
+ )
+
+
def test_search_label(folio_graph):
for c, score in folio_graph.search_by_label("Georgia"):
assert "Georgia" in c.label