| name | config-discovery |
| description | Schema Alignment & Unified View Engine — semantic field classification, OpenAPI integration, and schema evolution |
| metadata | {"version":"3.0.0","author":"OLAV Platform Team","type":"agent","category":"system-administration","intent":"schema_alignment_unified_view_evolution"} |
| tools | ["classify_field","create_unified_view","register_api_schema","trigger_schema_evolve","fuzzy_map_schema","run_topology_sandbox","discover_view_schemas","sync_schema_reference","scaffold_domain_agent"] |
| static_context | [{"path":"./references/BASELINE_SCHEMA.md"}] |
Overview
The Discovery Subagent handles semantic schema alignment, unified view generation,
and schema evolution for any domain integrated with OLAV — not just network vendors.
It implements a four-phase schema intelligence pipeline:
1. classify_field → vector-first tiered classification (Tier 0/1/2)
2. create_unified_view → auto-generate DuckDB VIEW from approved mappings
3. register_api_schema → ingest OpenAPI 3.x specs and classify all fields
4. trigger_schema_evolve → OPTICS clustering → propose new standard field names
Tools
classify_field (Phase 1)
Semantic field classification using vector similarity + optional LLM confirmation:
- Input:
field_metadata dict (name, description, type, example, command, domain)
- Tier 0 (confidence > 0.85): auto-matched via LanceDB vector search
- Tier 1 (0.60–0.85): LLM-confirmed with one zero-shot call
- Tier 2 (< 0.60): unclassified → staged in evolution pool
- Output:
{status, openconfig_path, confidence} (field is openconfig_path, NOT standard_name)
create_unified_view (Phase 3)
Auto-generate normalised DuckDB VIEWs from approved schema mappings:
- Input:
command (str), mappings (list of raw_key → openconfig_path dicts)
- Generates
v_unified_{command} VIEW with TRY_CAST for type safety
- Stages as
replace_view mutation → IngestManager applies atomically
- Output:
{view_name, column_count, sql_preview}
register_api_schema (Phase 4)
Parse an OpenAPI 3.x specification and classify every field:
- Input:
url_or_path (HTTP URL or local JSON file), domain, dry_run
- Extracts fields from
components/schemas and paths requestBody/responses
- Calls
classify_field for each → stages mutation requests
- Zero new pip dependencies (stdlib
urllib.request + json only)
- Output:
{fields_found, matched, llm_confirmed, unclassified, errors, staged}
trigger_schema_evolve (Phase 5)
Cluster unclassified fields and propose new standard names for human approval:
- Input:
domain, min_samples (OPTICS density threshold, default 3)
- Uses
sklearn.cluster.OPTICS (scikit-learn already in project deps)
- LLM zero-shot names each cluster → stages
propose_standard mutation
- Output:
{clusters_found, proposals, skipped}
- Approval:
olav config evolve --list / --approve <id>
fuzzy_map_schema
Legacy LLM-based normalisation for ad-hoc vendor data alignment:
- Input: vendor, command, raw_data (dict or list)
- Output: normalised data aligned to the baseline schema
- Config:
config/normalization_strategy.yaml
run_topology_sandbox
Graph-based topology analysis using NetworkX on live DuckDB views:
- Data source:
v_topo_links_clean view
- Graph:
nx.MultiGraph with CDP/LLDP/OSPF/BGP edges
- Algorithms: shortest_path, articulation_points, degree_centrality
- Output: nodes, edge_count, is_connected, cut_points, degree_centrality, mermaid
- Saves Mermaid diagram to
exports/network_topology.mmd
execute_sql
Direct DuckDB query execution with auto schema discovery:
- Auto schema discovery (no manual inspect_schema calls)
- DuckDB-specific optimisations
- SchemaContext singleton caching (5 min TTL)
discover_view_schemas
Auto-discover and register DuckDB view schemas for the SchemaContext cache.
