qualifier / backend /app /qualifier_common.py
Sethu0330's picture
Add FTL RFQ Qualifier agent + full SALES CRM app for HF Spaces testing
005df22 unverified
Raw History Blame Contribute Delete
20.7 kB
"""
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()
)