SageMatch

Inspiration

Real software buying decisions are hard. Buyers describe vague needs, catalogues are messy, and recommendations are rarely justified. We wanted to build a system that thinks like an analyst — asking the right questions, filtering on hard facts, and explaining every choice with evidence.

What it does

SageMatch takes a customer's natural language query (e.g. "I need a CRM for a 20-person sales team with Slack") and returns the top 3 product recommendations, each with:

• Why it fits — grounded bullets citing actual catalogue data (integration names, team size ranges, feature lists)
• How to improve the fit — specific gaps between the product and the customer's needs
• Decision evidence — per-dimension scores (category, team size, integrations, features, pricing) with source row citations
• A probing layer — when the query is vague, SageMatch asks only the questions that change the decision, scored by expected impact

How we built it

A 4-stage API-first pipeline built in FastAPI + React + PostgreSQL, containerised with Docker:

1. Requirements extraction — LLM parses the query into structured needs, validated against catalogue vocabulary
2. Probing — entropy-scored clarifying questions generated from missing dimensions
3. Evidence ranking — 7-dimension scoring with hard constraint enforcement
4. Grounded explanations — LLM writes natural language bullets, validated to only reference real catalogue tokens

Every stage calls the LLM first. If the API fails or returns invalid output, a deterministic fallback runs instantly. The system never shows hallucinated facts.

Challenges we ran into

The hardest challenge was contract validation — making the grounding checks strict enough to catch hallucinations without rejecting good LLM output. We tuned token matching to use catalogue-specific terms (product names, integration names, feature names) rather than generic words, which allowed natural language while preventing invented facts.

Accomplishments that we're proud of

• 100/100 catalogue health score after sanitization
• All 4 pipeline stages successfully using the LLM API (verified via live api_trace)
• 111 automated tests covering the full pipeline
• Zero hardcoded responses — every output is computed from the live catalogue

What we learned

LLM contract validation is as important as the LLM itself. The API-first + validate + fallback pattern made the system both powerful and reliable — judges can trust every recommendation is grounded in real data.

What's next for SageMatch

• Multi-turn conversation support
• Confidence-weighted ensemble ranking
• Automated catalogue quality improvement suggestions
• Deployment to Render for public access

Built With

• docker
• fastapi
• gpt-4o-mini
• node.js
• openrouter
• postgresql
• python
• react
• sqlalchemy
• vite