""" Qualifier skill compile/parse (SKILL.md <-> QualifierSkill row) and default-skill seeding. Deliberately a standalone copy of the same anatomy as chat_agent_common.py's compile_skill_md() / parse_skill_md(), not an import from it — the Qualifier's skill system is intentionally independent (own table, own file format instance, own UI) per the "separate copy per agent" design decision, so this module has zero dependency on the chat agent feature and could be lifted into a standalone service on its own. """ from __future__ import annotations import re from datetime import datetime from typing import Any, Dict, List, Optional import yaml from sqlalchemy.orm import Session from .database import QualifierSkill _FRONTMATTER_RE = re.compile(r"\A---\s*\n(.*?)\n---\s*\n?", re.DOTALL) _H3_RE = re.compile(r"^### (.+?)\s*$", re.MULTILINE) _SECTION_RE = re.compile(r"^## (References|Assets|Templates|Scripts|Evals)\s*$", re.MULTILINE) _EVAL_ITEM_RE = re.compile( r"^- \*\*Name:\*\* (.*?)\n" r"\s*\*\*Input:\*\* (.*?)\n" r"\s*\*\*Expected decision:\*\* (.*?)\n" r"\s*\*\*Expected project type:\*\* (.*?)\n" r"\s*\*\*Assertion \(([^)]*)\):\*\* (.*?)(?=\n- \*\*Name|\Z)", re.DOTALL | re.MULTILINE, ) def safe_str(value: Any) -> str: if value is None: return "" return str(value).strip() def _strip_code_fence(text: str) -> str: text = text.strip() m = re.match(r"^```[a-zA-Z0-9_+-]*\n(.*?)\n```$", text, re.DOTALL) if m: return m.group(1) return text def compile_skill_md(skill: QualifierSkill) -> str: """Render one Qualifier skill as a standalone, portable SKILL.md file.""" name = safe_str(skill.name) or f"qualifier-skill-{skill.id}" description = safe_str(skill.description) instructions = safe_str(skill.instructions) frontmatter = yaml.safe_dump( {"name": name, "description": description}, default_flow_style=False, sort_keys=False, allow_unicode=True, ).rstrip("\n") lines = ["---", frontmatter, "---", "", instructions, ""] references = skill.references_json or [] if references: lines.append("## References") lines.append("") for ref in references: title = safe_str(ref.get("title")) if isinstance(ref, dict) else "" content = safe_str(ref.get("content")) if isinstance(ref, dict) else "" lines.append(f"### {title or 'Untitled reference'}") lines.append("") lines.append(content) lines.append("") assets = skill.assets_json or [] if assets: lines.append("## Assets") lines.append("") for asset in assets: aname = safe_str(asset.get("name")) if isinstance(asset, dict) else "" content = safe_str(asset.get("content")) if isinstance(asset, dict) else "" lines.append(f"### {aname or 'Untitled asset'}") lines.append("") lines.append("```") lines.append(content) lines.append("```") lines.append("") templates = skill.templates_json or [] if templates: lines.append("## Templates") lines.append("") for template in templates: tname = safe_str(template.get("name")) if isinstance(template, dict) else "" content = safe_str(template.get("content")) if isinstance(template, dict) else "" lines.append(f"### {tname or 'Untitled template'}") lines.append("") lines.append("```") lines.append(content) lines.append("```") lines.append("") scripts = skill.scripts_json or [] if scripts: lines.append("## Scripts") lines.append("") lines.append("_Stored for documentation and portability only — never executed by the agent._") lines.append("") for script in scripts: sname = safe_str(script.get("name")) if isinstance(script, dict) else "" slang = safe_str(script.get("language")) if isinstance(script, dict) else "" sdesc = safe_str(script.get("description")) if isinstance(script, dict) else "" scontent = safe_str(script.get("content")) if isinstance(script, dict) else "" header = f"### {sname or 'Untitled script'}" if slang: header += f" ({slang})" lines.append(header) lines.append("") if sdesc: lines.append(sdesc) lines.append("") lines.append(f"```{slang}") lines.append(scontent) lines.append("```") lines.append("") evals = skill.evals_json or [] if evals: lines.append("## Evals") lines.append("") for ev in evals: if not isinstance(ev, dict): continue lines.append(f"- **Name:** {safe_str(ev.get('name'))}") lines.append(f" **Input:** {safe_str(ev.get('input_ref'))}") lines.append(f" **Expected decision:** {safe_str(ev.get('expected_decision'))}") lines.append(f" **Expected project type:** {safe_str(ev.get('expected_project_type'))}") lines.append( f" **Assertion ({safe_str(ev.get('assertion_type'))}):** {safe_str(ev.get('assertion_value'))}" ) lines.append("") return "\n".join(lines).rstrip() + "\n" def _parse_h3_items(section_body: str, key: str) -> list: items = [] parts = _H3_RE.split(section_body) for i in range(1, len(parts), 2): title = parts[i].strip() body = (parts[i + 1] if i + 1 < len(parts) else "").strip() if key == "name": body = _strip_code_fence(body) items.append({key: title, "content": body}) return items def _parse_scripts_section(section_body: str) -> list: scripts = [] parts = _H3_RE.split(section_body) for i in range(1, len(parts), 2): header = parts[i].strip() body = (parts[i + 1] if i + 1 < len(parts) else "").strip() m = re.match(r"^(.*?)\s*\(([^)]+)\)\s*$", header) sname, slang = (m.group(1).strip(), m.group(2).strip()) if m else (header, "") fence_m = re.search(r"```([a-zA-Z0-9_+-]*)\n(.*?)\n```", body, re.DOTALL) if fence_m: slang = slang or fence_m.group(1) scontent = fence_m.group(2) sdesc = body[: fence_m.start()].strip() else: scontent = body sdesc = "" scripts.append({"name": sname, "description": sdesc, "language": slang, "content": scontent}) return scripts def _parse_evals_section(section_body: str) -> list: evals = [] for m in _EVAL_ITEM_RE.finditer(section_body.strip() + "\n"): evals.append( { "name": m.group(1).strip(), "input_ref": m.group(2).strip(), "expected_decision": m.group(3).strip() or None, "expected_project_type": m.group(4).strip() or None, "assertion_type": m.group(5).strip(), "assertion_value": m.group(6).strip(), } ) return evals def parse_skill_md(content: str) -> dict: """Parse a Qualifier SKILL.md back into a dict of fields, matching compile_skill_md()'s format. Best-effort on References/Assets/Templates/Scripts/Evals — a hand-edited file that omits or reformats a section yields an empty list for it, never an error.""" content = (content or "").replace("\r\n", "\n").strip("\n") name = "" description = "" body = content fm_match = _FRONTMATTER_RE.match(content + "\n") if fm_match: block = fm_match.group(1) try: data = yaml.safe_load(block) except yaml.YAMLError: data = None if isinstance(data, dict): name = safe_str(data.get("name")) description = safe_str(data.get("description")) body = content[fm_match.end():] parts = _SECTION_RE.split(body) instructions = parts[0].strip() references: list = [] assets: list = [] templates: list = [] scripts: list = [] evals: list = [] for i in range(1, len(parts), 2): section_name = parts[i] section_body = parts[i + 1] if i + 1 < len(parts) else "" if section_name == "References": references = _parse_h3_items(section_body, "title") elif section_name == "Assets": assets = _parse_h3_items(section_body, "name") elif section_name == "Templates": templates = _parse_h3_items(section_body, "name") elif section_name == "Scripts": scripts = _parse_scripts_section(section_body) elif section_name == "Evals": evals = _parse_evals_section(section_body) return { "name": name, "description": description, "instructions": instructions, "references": references, "assets": assets, "templates": templates, "scripts": scripts, "evals": evals, } def skill_to_dict(skill: QualifierSkill) -> Dict[str, Any]: return { "id": skill.id, "name": skill.name or "", "description": skill.description or "", "instructions": skill.instructions or "", "references": skill.references_json or [], "assets": skill.assets_json or [], "templates": skill.templates_json or [], "scripts": skill.scripts_json or [], "evals": skill.evals_json or [], "is_default": bool(skill.is_default), "is_active": bool(skill.is_active), "sort_order": skill.sort_order or 0, "created_at": skill.created_at.isoformat() if skill.created_at else None, "updated_at": skill.updated_at.isoformat() if skill.updated_at else None, } def get_default_skill_content() -> Dict[str, Any]: """The seed skill for a fresh tenant — the qualify policy locked with Seth, encoded as the skill's always-applied instructions, plus the reference material and evals discussed. Admins can edit every field afterward; this is just the starting point so the agent isn't empty on day one.""" instructions = """# FTL Distribution — RFQ Qualifier You are FTL Distribution's RFQ qualification analyst. FTL is Canada's exclusive distributor of Wittur elevator components (door operators, roller guides, safety gear/governors, door protection), selling only to elevator contractors and service companies. Your job: given one incoming RFQ/tender (an email and/or its attached specification), decide whether FTL should pursue it — qualify, disqualify, or flag for human review — within the same 24-business-hour SLA FTL commits to for a human doing this job. ## Non-goals - Do not price anything — that is the Quote Estimator agent's job, not yours. - Do not draft the customer-facing reply — only the internal decision and reasoning. - Do not guess at information the RFQ doesn't state (e.g. a missing deadline) — flag it, don't invent it. ## Step 1 — triage every equipment line item you find into one of three buckets - **Out of scope**: motors, machine brakes, controllers, solid-state drives, encoders, cab interior /renovation, wiring, hall lanterns, hall stations, lobby panels, sheaves, car slings, buffers, pit steel — anything FTL doesn't sell. Drop these silently; their presence (even if most of the RFQ) has no bearing on the decision. - **In scope, exact match**: door operators, car door clutches, panel adaptors, universal car door panels, roller guide assemblies (car & counterweight), governors, unidirectional car safeties, door protective devices/detectors — described in a way that maps cleanly onto the Wittur catalog (use the search_pricelist tool to confirm). Look these up. - **Ambiguous**: right category (one of the above), but something doesn't cleanly match the current pricelist — an OEM not covered, an unusual size, a configuration not listed (e.g. a duplex safety variant). Still counts as in-scope for qualifying purposes, but flag it `needs_engineering_review` in your output rather than guessing at a match. ## Step 2 — qualify threshold A single in-scope or ambiguous item is enough to qualify on the item-matching dimension alone. Do not require full-RFQ coverage — most tenders are majority out-of-scope by nature (a tender covers the whole elevator; FTL supplies a handful of subsystems within it), and that is normal, not a reason to disqualify. ## Step 3 — project-type override Classify the project as **modernization** or **new_construction**. Modernization tenders (a retrofit of an existing elevator, typically structured as three linked spec sections — a general bid-instructions section, a general technical-modernization section, and a per-car/per-building technical schedule) are the qualify-favoring signal. New-construction tenders (a single consultant-authored specification covering the entire elevator system as one engineered package — often structured as PART 1 GENERAL / PART 2 PRODUCTS / PART 3 EXECUTION) should default to **disqualify** even when in-scope items are technically requested, because of warehouse/inventory tie-up and the length of such projects — mirroring FTL's own stated reasoning on a real new-construction RFQ: "we do not quote 95% of the time, due to length of project and total amount/area of equipment needed. It would pack my warehouse." If you're not confident which type it is, say `project_type: "unknown"` and lean toward `needs_review` rather than guessing. ## Step 4 — output Always call submit_qualification_decision with your full structured decision — matched items, excluded items, flags, the stated deadline if any, your reasoning tying back to these rules, and a confidence score. Reasoning should be specific enough that a human reviewing your call can see exactly which items and which signals drove it.""" references = [ { "title": "Product-line / OEM compatibility guide", "content": ( "Door operators (Wittur SGV2): types 2T (2-speed side opening), 2C (center " "opening/bi-parting), 1S (single-speed side opening); door hand LH/RH; widths " "36\"/42\"/48\"; OEM panel-adaptor compatibility covers Otis, Westinghouse, GAL, " "MAC, Dover (interlock/clutch is OEM-specific — Otis, Westinghouse \"WEST\", GAL " "\"G.M.D.\" — and priced separately from the operator itself; a door operator PO " "must include a clutch c/w car door interlock).\n\n" "Roller guides: frame sizes RG80/RG100/RG125/RG150/RG200/RG300, sold per 4-piece " "set, for both car and counterweight application, OEM-agnostic (\"ALL\").\n\n" "Governors: OL35-MT (manual trip), OL35-RC (remote control), OL35-RE " "(remote+encoder) — plus a swingarm tension weight/sheave assembly for the " "counterweight side. Unidirectional car safeties are sold as a synchronized set of " "2 (\"sync\"); heavier/larger cars may need a duplex (2-safety-set) configuration, " "which may not always be an exact pricelist SKU — treat as ambiguous/needs review " "if so, not as unsupported." ), }, { "title": "Modernization vs. new-construction classification guide", "content": ( "Modernization tender structural signature: three linked spec sections, commonly " "numbered 14000 (general/bid instructions — tender submittal deadline, bid bond, a " "tender form with an equipment-manifest questionnaire asking the bidder to state " "existing make/model for controllers, door operators, roller guides, governor, " "etc.), 14100 (general technical modernization spec, organized by system: Machine " "Room / Hoistway Equipment / Elevator Cab / Elevator Control & Dispatching), and " "14900 (a per-car/per-building schedule with the actual existing-equipment " "make/model and performance data). This is the qualify-favoring signature.\n\n" "New-construction tender structural signature: a single consultant-authored " "specification (no split general/schedule sections) covering literally every " "elevator subsystem from scratch — commonly structured as PART 1 - GENERAL / PART " "2 - PRODUCTS (covering motors, controllers, cab, doors, safeties, fixtures, " "everything) / PART 3 - EXECUTION. If you see this shape, or the spec explicitly " "describes a new building/new installation rather than a retrofit of existing " "equipment, classify as new_construction and default toward disqualify per the " "policy above." ), }, { "title": "Ambiguous-item handling — worked example", "content": ( "A real FTL quote included \"CSGB03-D_CAR_SAFETIES_DUPLEX\" (a duplex unidirectional " "safety configuration) even though the standard pricelist only lists the single " "\"CSGB03-SYNC\" safety set. The right call here: still in-scope (it's a car safety, " "a category FTL sells), but flag `needs_engineering_review` since the exact " "configuration isn't a confirmed catalog line — do not treat an unlisted " "variant within a supported category as out-of-scope, and do not silently assume " "an exact price/SKU match either." ), }, ] templates = [ { "name": "internal-qualified-notification", "content": ( "Subject: [QUALIFY] {project_name}\n\n" "FTL can quote this one. Matched: {matched_items_summary}.\n" "Project type: {project_type}. Deadline: {deadline}.\n" "Flags: {flags}.\n\n" "Reasoning: {reasoning}" ), }, { "name": "internal-disqualify-notification", "content": ( "Subject: [DISQUALIFY] {project_name}\n\n" "Recommending we pass on this one — for your review before it's actually declined.\n" "Project type: {project_type}.\n\n" "Reasoning: {reasoning}" ), }, ] return { "name": "ftl-rfq-qualifier", "description": ( "Qualifies incoming elevator-parts RFQs for FTL Distribution — decides qualify / " "disqualify / needs_review within FTL's 24-business-hour SLA, using the Wittur " "pricelist as its only knowledge base. Always active." ), "instructions": instructions, "references": references, "assets": [], "templates": templates, "scripts": [], "evals": [], } def get_or_create_default_skill(db: Session, tenant_id: int) -> QualifierSkill: existing = ( db.query(QualifierSkill) .filter(QualifierSkill.tenant_id == tenant_id) .order_by(QualifierSkill.sort_order, QualifierSkill.id) .first() ) if existing: return existing seed = get_default_skill_content() skill = QualifierSkill( tenant_id=tenant_id, name=seed["name"], description=seed["description"], instructions=seed["instructions"], references_json=seed["references"], assets_json=seed["assets"], templates_json=seed["templates"], scripts_json=seed["scripts"], evals_json=seed["evals"], is_default=1, is_active=1, sort_order=0, ) db.add(skill) db.flush() return skill def get_active_skill(db: Session, tenant_id: int) -> Optional[QualifierSkill]: """The skill the run pipeline should use: the lowest-sort_order active skill for the tenant. (Multiple skills can exist for experimentation, but exactly one drives live runs — same single-active-config assumption as ChatAgentConfig, kept simple rather than letting a run specify an arbitrary skill_id from the UI in v1.)""" return ( db.query(QualifierSkill) .filter(QualifierSkill.tenant_id == tenant_id, QualifierSkill.is_active == 1) .order_by(QualifierSkill.sort_order, QualifierSkill.id) .first() )