0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00
mastra/templates/template-lead-qualification
Diego Antunes ec35d91a79
feat(templates): add lead qualification template (#27839)
## Description

Adds `template-lead-qualification`, an official Mastra template for
researching companies and qualifying incoming leads against a
configurable ideal customer profile (ICP).

Supports JSON API or Attio intake, source-backed research through
OpenAI, deterministic scoring, and human review for uncertain results.
Includes durable workflow recovery, local Markdown reports or Attio
output, telemetry, evaluation tooling, documentation, and a demo.

**All `@mastra/*` packages and the `mastra` CLI use `"latest"`,
following the explicit requirements in the [official templates
README](https://github.com/mastra-ai/mastra/blob/main/templates/README.md).**

Includes unit and integration tests covering intake, qualification,
evidence validation, human review, Attio adapters, recovery, evaluation,
and telemetry.

## Related issue(s)

The issue requirement is waived for this contribution: this is a new
feature delivered as an official Mastra template and developed by a
member of the Mastra organization.

## Type of change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [x] Test update

## Checklist

- [x] Related issue requirement waived for this contribution (see above)
- [x] I have made corresponding changes to the documentation (if
applicable)
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] I have addressed all Coderabbit comments on this PR

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5

This PR adds a ready-to-use Mastra template that checks whether new
company leads match a configurable ideal customer profile. It researches
companies, scores leads, requests human review when needed, and safely
recovers after interruptions.

## Summary

- Adds the official `template-lead-qualification` template.
- Supports JSON API and Attio intake, with local Markdown or Attio
output.
- Adds OpenAI-backed research with source, citation, domain, and
evidence validation.
- Adds deterministic scoring for business model, employee count,
headquarters, and buying intent.
- Adds human review, approval, reopening, conflict handling, and output
reconciliation.
- Adds durable storage, retries, idempotency, restart recovery, and
uncertain-write recovery.
- Adds privacy-filtered telemetry, evaluation tooling, quality fixtures,
reporting, and retention maintenance.
- Adds Attio setup tooling, webhook authentication, mapping validation,
and migration support.
- Adds documentation, demos, and unit and integration tests.
- Documents the requirement to use `"latest"` for `@mastra/*` packages
and the `mastra` CLI.

## Validation

Recent changes also address dispatch after input-drain failures,
rejected-evidence isolation, internationalized email domains, report
ordering, diagnostic URL stability, maintenance CLI locking, and
semantic evaluation reviews. Test execution results are not available in
the supplied evidence.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Alex Booker <booker@booker.codes>
History 2026-10-21 09:44:58 +01:00
..
docs feat(templates): add lead qualification template (#27839) 2026-10-21 09:44:58 +01:00
scripts feat(templates): add lead qualification template (#27839) 2026-10-21 09:44:58 +01:00
src/mastra feat(templates): add lead qualification template (#27839) 2026-10-21 09:44:58 +01:00
tests feat(templates): add lead qualification template (#27839) 2026-10-21 09:44:58 +01:00
.env.example feat(templates): add lead qualification template (#27839) 2026-10-21 09:44:58 +01:00
.gitignore feat(templates): add lead qualification template (#27839) 2026-10-21 09:44:58 +01:00
.oxfmtrc.json feat(templates): add lead qualification template (#27839) 2026-10-21 09:44:58 +01:00
CONTRIBUTING.md feat(templates): add lead qualification template (#27839) 2026-10-21 09:44:58 +01:00
oxlint.config.ts feat(templates): add lead qualification template (#27839) 2026-10-21 09:44:58 +01:00
package.json feat(templates): add lead qualification template (#27839) 2026-10-21 09:44:58 +01:00
README.md feat(templates): add lead qualification template (#27839) 2026-10-21 09:44:58 +01:00
tsconfig.json feat(templates): add lead qualification template (#27839) 2026-10-21 09:44:58 +01:00
vitest.config.ts feat(templates): add lead qualification template (#27839) 2026-10-21 09:44:58 +01:00

Lead Qualification

A Mastra workflow triages and qualifies leads received through a JSON API or Attio CRM. It researches each company, compares the findings with your sales team's ideal customer profile (ICP), and produces a score and qualification outcome with supporting sources. Results go to a local report or Attio; uncertain cases go to human review.

Why we built this

Sales teams need to know whether incoming leads match their ICP. Manually researching every company and checking it against the qualification criteria is tedious, so we built this template to automate the initial research and triage.

Demo

Prerequisites

  • OpenAI API key: set OPENAI_API_KEY for the default GPT-6 Luna research provider, which searches company sources and checks extracted facts.
  • Attio workspace token: optional. Set ATTIO_API_TOKEN and generate the list mapping to use Attio output. Attio input also requires ATTIO_WEBHOOK_SECRET. See Attio configuration.

Quickstart 🚀

  1. Create the project
    • Run npx create-mastra@latest lead-qualification --template lead-qualification, then cd lead-qualification and npm install.
  2. Add your API key
    • Run cp .env.example .env and fill in the key described under Prerequisites. Both providers default to local.
  3. Start the server
    • Run npm run dev and open Mastra Studio.
    • Submit the request below, then open the returned statusUrl to read the assessment and business.state. Inspect the run under Workflows → lead-intake in Studio. The result explains the company's fit and flags facts that need review.
curl http://localhost:4111/lead-qualification/events \
  -H 'Content-Type: application/json' \
  -d '{"version":1,"type":"lead.received","eventId":"company-1","lead":{"reference":"mastra","domain":"mastra.ai"}}'

Try it out

  • Add a genuine lead.inquiry using the input contract. Its date and request type contribute to buying intent; a company's own demo offer doesn't.
  • For an uncertain result, open Tools → reviewLead in Studio and copy the current packet's references from the run response. Approve, reject, or request changes, then read /lead-qualification/runs/<runId>/output for the local Markdown report.
  • Select Attio input and output to qualify new Triage entries and review uncertain cases by moving Stage.
  • Resend an event with the same ID to retrieve its existing run. To research a completed lead again, submit a new ID and its latest supersedesAssessmentId.

Customization

About Mastra templates

This is an official Mastra template. Official templates live in the Mastra monorepo and are synchronized to standalone repositories.

Want to contribute?