mirror of
https://github.com/mastra-ai/mastra.git
synced 2026-11-17 08:44:46 +00:00
## 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
|
|
|---|---|---|
| .. | ||
| docs | ||
| scripts | ||
| src/mastra | ||
| tests | ||
| .env.example | ||
| .gitignore | ||
| .oxfmtrc.json | ||
| CONTRIBUTING.md | ||
| oxlint.config.ts | ||
| package.json | ||
| README.md | ||
| tsconfig.json | ||
| vitest.config.ts | ||
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_KEYfor the default GPT-6 Luna research provider, which searches company sources and checks extracted facts. - Attio workspace token: optional. Set
ATTIO_API_TOKENand generate the list mapping to use Attio output. Attio input also requiresATTIO_WEBHOOK_SECRET. See Attio configuration.
Quickstart 🚀
- Create the project
- Run
npx create-mastra@latest lead-qualification --template lead-qualification, thencd lead-qualificationandnpm install.
- Run
- Add your API key
- Run
cp .env.example .envand fill in the key described under Prerequisites. Both providers default tolocal.
- Run
- Start the server
- Run
npm run devand open Mastra Studio. - Submit the request below, then open the returned
statusUrlto read the assessment andbusiness.state. Inspect the run under Workflows → lead-intake in Studio. The result explains the company's fit and flags facts that need review.
- Run
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.inquiryusing 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>/outputfor 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
- Ask your coding agent: “Explore the code and propose a plan to qualify companies for my target market. Adjust the criteria, score weights, and review policy while preserving sourced evidence.” Start with qualification configuration.
- Choose separate input and output providers, add a research source, or adapt reports and telemetry. Operations covers deployment and recovery.
About Mastra templates
This is an official Mastra template. Official templates live in the Mastra monorepo and are synchronized to standalone repositories.