Tuning & Customization

Uploading documents is step one. Making Planara actually useful for a specific customer requires tuning — bridging the gap between how technicians ask questions and how manufacturers write manuals.

Every industry, manufacturer, and customer has different vocabulary, fault code systems, safety standards, and workflows. This guide covers what needs to be customized and how.

What Needs Tuning

Ontology Expansion

What it is

The ontology bridges vocabulary gaps between how technicians ask questions and how manufacturers write manuals. When a tech asks "how do I winterize?" the ontology expands the query to include terms the manual actually uses: "storing transporting vapor separator drain flush."

Where it lives

Each vertical has its own ontology definition (marine today; factory and HVAC are planned).

Structure

Two types of expansion:

Acronyms — appended when the acronym appears in the query:

acronyms:
  USCG: "United States Coast Guard"
  VST: "Vapor Separator Tank"
  TDC: "Top Dead Center"

Associations — context terms added when a phrase is detected:

associations:
  oil change: "cowling removal top cowling lock lever"
  thermostat: "cooling system overheat temperature water pump"
  winterize: "storing transporting vapor separator drain flush"

How to build an ontology for a new customer

1. Read the manuals — identify the specific terminology the manufacturer uses
2. Interview technicians — ask "how do you describe this problem?" and compare to manual language
3. Check retrieval misses — run queries that techs would actually ask, see which ones get low confidence. Those are your ontology gaps.
4. Add associations — map the tech's words to the manual's words
5. Verify against the index — every association term MUST exist in the actual ingested documentation. Don't add terms that aren't in the index.

Example: Marine vertical

A tech asks: "P0217 overheat alarm"

Without ontology: the search index looks for "P0217" — not found in Yamaha manual (they use "trouble code 46").

With ontology:

P0217: "overheat trouble code 46 thermoswitch cooling water temperature alert"
overheat alarm: "trouble code 46 thermoswitch buzzer cooling water pilot hole water pump thermostat"

Now the query expands to include "trouble code 46" and "thermoswitch" — direct hits in the Yamaha manual.

Fault Code Mapping

The problem

Every manufacturer has their own fault code system. Technicians' diagnostic tools often report OBD-II generic codes (P0217, P0300) but the manufacturer's service manual uses proprietary codes (Yamaha: trouble code 46, trouble code 21).

If Planara doesn't translate between these systems, it will say "code not documented" even when the relevant troubleshooting section exists.

How it works

Fault codes are mapped in two places:

1. Ontology YAML — for retrieval expansion:

P0217: "overheat trouble code 46 thermoswitch cooling water temperature alert"
P0300: "misfire trouble code 21 22 23 24 cylinder ignition spark plug coil"

2. Fault code library — for structured context injection:

{
  "P0217": {
    "description": "Engine Coolant Over Temperature",
    "system": "cooling",
    "common_causes": ["Thermostat stuck closed", "Low coolant", "Water pump failure"],
    "related_codes": ["P0116", "P0117", "P0118"],
    "severity": "critical"
  }
}

Both are needed: the ontology fixes retrieval, the structured context helps generation reason about the code.

Building fault code maps for a new manufacturer

1. Get the manufacturer's trouble code list from their service manual
2. Map each to the equivalent OBD-II code (many manuals include this cross-reference)
3. Add both directions to the ontology: P0217 → manufacturer terms AND manufacturer terms → OBD-II context
4. Add structured entries to the fault code library with common causes and severity
5. Test with real diagnostic queries to verify the mapping works

Skill Configuration

What skills are

Skills are query-type-specific response strategies. A "torque spec" question needs a different approach than a "diagnostic" question or a "safety" question.

Default skills

Vertical overrides

Each vertical can override skill behavior with its own configuration (for example, a marine pre_season skill or a factory safety skill).

Adding skills for a new vertical

1. Identify the common query categories for that industry
2. Create skill configs with trigger keywords and response augmentations
3. Add vertical-specific response guidance (e.g., factory safety emphasizes LOTO, marine emphasizes electrical isolation)

CKL (Compliance Standards)

Configured per-tenant in the backoffice. See the CKL documentation for details.

Key per-customer decisions:

• Which industry standards apply (ABYC for marine, OSHA for factory, EPA for HVAC refrigerant)
• Trigger terms — what topics activate compliance checks
• Relevance threshold — how closely a standard must match to be included
• Whether to enable the Standards Discovery Wizard for auto-setup

Onboarding Checklist

When setting up a new customer:

Week 1: Foundation

• Ingest all manufacturer documents (service manuals, owner's manuals, parts catalogs, TSBs)
• Set document types and equipment scoping
• Run initial eval suite — establish baseline accuracy
• Identify top 20 queries technicians will ask (interview or survey)

Week 2: Tuning

• Build ontology associations from retrieval misses
• Map fault codes (OBD-II → manufacturer, and vice versa)
• Configure skill routing (may need vertical-specific overrides)
• Set up CKL with relevant industry standards
• Configure roles and permissions
• Move auto-generated evals to Trial status
• Run first trial eval suite
• Review trial results with domain expert
• Promote passing trials to Golden baseline

Week 3: Validation

• Run full eval suite — compare to baseline
• Test the top 20 queries manually — verify quality
• Fix any retrieval misses with ontology additions
• Fix any generation issues with response tuning
• Generate multi-stream eval queries (with telemetry, fault codes)
• Run trial evals after ontology changes
• Compare trial vs official metrics
• Promote stable trials to Golden

Week 4: Soft Launch

• Enable for 2-3 pilot technicians
• Monitor product analytics for usage patterns
• Review negative feedback daily
• Auto-generate eval queries from feedback
• Iterate on ontology and response tuning based on real usage

Per-Customer Config Files

For each customer deployment, maintain:

configs/
  {customer}/
    ontology.yaml          # Vocabulary mappings
    fault_codes.yaml       # Code translation table
    ckl_triggers.yaml      # Compliance trigger terms
    eval_baseline.json     # Baseline eval scores
    notes.md               # Customer-specific tuning notes

This becomes the "recipe" for that customer's deployment. When re-deploying or migrating, these configs ensure the tuning is preserved.

When Tuning Isn't Enough

Sometimes the issue isn't tuning — it's missing content:

• Manual gaps: The manufacturer's documentation doesn't cover a common procedure. Solution: upload supplementary content (TSBs, training guides, field bulletins).
• Diagram quality: Wiring diagrams are low-resolution scans. Solution: request better source files or use diagram enhancement (planned).
• Language mismatch: Manual is in formal English, techs speak colloquially. Solution: heavy ontology expansion plus question-style indexing applied at ingestion time.
• Cross-model confusion: Multiple engine models share similar but not identical procedures. Solution: equipment scoping + model-specific document tagging.