Working name. The platform built from BUILD_PLAN.md v0.3 (hybrid) and ULTIMATE_BUILD_GUIDE.md v0.5 (post-council). Phase 0 complete: end-to-end pipeline from
(name, city, state)to fully styled deliverables in minutes for cents.
┌──────────────────────────────────────────────┐
│ Input: company name + city + state │
│ (or fully-hand-filled target/mandate JSON) │
└──────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────┐
│ ENRICHMENT PIPELINE │
│ web_research → apollo → llm_inference │
│ (paid stubs: coresignal, builtwith, │
│ state-license, ucc — see roadmap) │
└──────────────────────────────────────────────┘
│
┌───────────────────┴───────────────────┐
▼ ▼
┌───────────────────────────┐ ┌─────────────────────────────┐
│ BUYER SIDE │ │ ADVISOR SIDE │
│ • Outreach Brief (docx) │ │ • Teaser (docx) │
│ • 5-touch outreach (docx)│ │ • Buyer List (xlsx) │
│ │ │ • CIM Scaffold (docx) │
│ │ │ • Comps + Valuation (xlsx) │
└───────────────────────────┘ └─────────────────────────────┘
Every output is IB-grade styled (Arial, navy accents, real Word tables/numbering, no unicode bullets), follows the canonical Anthropic claude-skills docx + xlsx skill patterns, and passes the banned-phrase + confidence-tagger gates.
- Banned-phrase filter — "leverage synergies", "value-add", "drive growth without a channel" etc. blocked at output time
- Confidence tagging — every inferred number carries
(est, conf: 0.X, src: method) - Adapter priority + merge — high-confidence sources always win on field merges; no silent fabrication
cd "C:\Users\guilh\OneDrive\Documentos\Claude Brain\ai-ma-platform"
# Setup (once)
Copy-Item ..\llm-council\.env .env # or paste your own keys
uv sync --python "C:\Users\guilh\AppData\Local\Programs\Python\Python312\python.exe"
cd dealbrain\templates\docx_js ; npm install ; cd ..\..\..
# Single brief from minimal input (~20s, ~$0.002)
uv run python -m scripts.enrich_target "Coastal Air Services" Tampa FL --also-brief
# Single brief from full target JSON (~7-15s, ~$0.001)
uv run python -m scripts.generate_brief examples/sample_target.json --export docx,html
# Batch from CSV (the Phase 0 unlock — see examples/searcher_mandate.csv)
uv run python -m scripts.batch_enrich examples/searcher_mandate.csv
# Full advisor Engagement Pack (~50s, ~$0.005)
uv run python -m scripts.generate_pack examples/sample_mandate.json --export docx,xlsx
# Cold outreach sequence informed by a brief (~6s, ~$0.001)
uv run python -m scripts.generate_outreach examples/sample_target.json `
--brief examples/sample_target.brief.md --export docx| Script | Input | Output | Time | Cost (cheap mode) |
|---|---|---|---|---|
scripts/enrich_target.py |
name + city + state | enriched JSON + brief | ~20s | ~$0.002 |
scripts/batch_enrich.py |
CSV of names | folder of briefs + summary CSV | ~20s/row | ~$0.002/row |
scripts/generate_brief.py |
enriched JSON | brief.md + .docx + .html + meta | ~7-15s | ~$0.001 |
scripts/batch_generate.py |
folder of JSONs | folder of briefs + summary CSV | ~7s/target | ~$0.001/target |
scripts/generate_pack.py |
sell-side mandate JSON | 4-artifact pack (md/docx/xlsx) | ~50s | ~$0.005 |
scripts/generate_outreach.py |
target JSON + brief.md | 5-touch outreach sequence | ~6s | ~$0.001 |
Set MODE=production in .env to use the full LLM Council instead of cheap-mode (premium models, 20-30× cost, dramatically better quality).
ai-ma-platform/
├── BUILD_PLAN.md # v0.3 hybrid plan
├── ULTIMATE_BUILD_GUIDE.md # v0.5 post-council ultimate guide
├── PAID_UPGRADES_ROADMAP.md # ← read when revenue starts coming in
├── README.md # this file
├── pyproject.toml # uv-managed deps
├── .env # API keys (gitignored)
│
├── dealbrain/ # Python package
│ ├── config.py # env loading, MODE switching
│ ├── openrouter_client.py # single-model OpenRouter calls
│ ├── council_client.py # full LLM Council (via :8001)
│ ├── brief_generator.py # Tier 0 → 1 → 2 brief pipeline
│ ├── engagement_pack.py # advisor-side 4-artifact pack
│ ├── outreach.py # 5-touch cold outreach sequence
│ ├── export.py # generic md → html/docx via pandoc
│ ├── filters/
│ │ ├── banned_phrases.py # hard + conditional banned-phrase scanner
│ │ └── confidence_tagger.py # audit + auto-tag fallback
│ ├── verticals/hvac/
│ │ ├── signal_ontology.yaml # structured strong/medium/weak signals
│ │ └── deal_archetypes.md # 3 canonical archetypes + 13 levers
│ ├── enrichment/ # adapter pipeline
│ │ ├── orchestrator.py # priority-merge + confidence-tagging
│ │ ├── schema.py # FieldProvenance + target schema
│ │ └── adapters/
│ │ ├── web_research.py # DDG + httpx + LLM extract (free)
│ │ ├── apollo.py # Apollo.io enrich + cache (free tier)
│ │ ├── llm_inference.py # honest-low-confidence gap fill
│ │ └── stubs.py # Coresignal/BuiltWith/state/UCC stubs
│ ├── templates/ # structured renderers
│ │ ├── docx_js/ # Node.js docx-js renderers
│ │ │ ├── brief_renderer.cjs # buyer-side brief
│ │ │ ├── teaser_renderer.cjs # advisor-side teaser
│ │ │ ├── cim_renderer.cjs # advisor-side CIM (multi-page + TOC)
│ │ │ └── outreach_renderer.cjs # 5-touch outreach sequence
│ │ ├── brief_docx_renderer.py # python-docx fallback
│ │ ├── cim_docx_js.py # CIM Python wrapper
│ │ ├── teaser_docx_js.py # teaser Python wrapper
│ │ ├── outreach_docx_js.py # outreach Python wrapper
│ │ ├── buyer_list_xlsx.py # openpyxl IB-style buyer list
│ │ └── comps_xlsx.py # openpyxl 5-sheet financial model
│ └── skills/ # 17 SKILL.md files documenting every component
│
├── examples/
│ ├── sample_target.json # canonical brief input example
│ ├── sample_mandate.json # canonical pack input example
│ ├── synthetic_batch/ # 10 synthetic HVAC targets + Project Magnolia mandate
│ ├── searcher_mandate.csv # sample CSV for batch enrichment
│ └── enriched_batch/ # output of batch_enrich.py runs
│
└── scripts/ # CLIs
├── enrich_target.py
├── batch_enrich.py
├── generate_brief.py
├── batch_generate.py
├── generate_pack.py
└── generate_outreach.py
Each skill is documented in dealbrain/skills/<skill-name>/SKILL.md:
| Skill | Purpose |
|---|---|
outreach-brief-generator |
Tier 0 → 1 → 2 brief pipeline |
engagement-pack-assembler |
4-artifact advisor pack |
cold-outreach-sequencer |
5-touch outreach in operator voice |
target-enrichment-pipeline |
(name, city, state) → enriched JSON |
confidence-tagger |
"no silent estimates" enforcement |
banned-phrase-filter |
Anti-consultant-slop quality gate |
hvac-signal-ontology |
Structured strong/medium/weak signals for HVAC |
brief-docx-renderer |
IB-grade docx-js brief |
teaser-docx-renderer |
IB-grade docx-js teaser |
cim-docx-renderer |
Multi-page docx-js CIM with cover + TOC |
outreach-docx-renderer |
5-touch outreach docx with day badges |
buyer-list-xlsx-renderer |
openpyxl IB-color-coded buyer list |
comps-xlsx-renderer |
openpyxl 5-sheet financial model with formulas |
Phase 1 build queue — see PAID_UPGRADES_ROADMAP.md for every paid component with cost / unlock / wiring effort:
- Coresignal (LinkedIn-derived succession signals) — biggest single quality jump
- BuiltWith Pro (real field-service-software detection)
- State HVAC license registries (FL DBPR, TX TDLR, GA CILB)
- UCC liens / distress signals
- Real PDF rendering (currently HTML → browser-print)
- PPTX renderer (for pitch decks)
- Web UI (currently CLI-only)
- Multi-tenant Postgres (currently JSON files)
- Affinity CRM native integration
- Outreach.io / Smartlead sequencer integration
- SOC 2 prep (for enterprise advisor customers)
- Brand customization tokens
Architecture is deliberately built so every deferred item is a drop-in replacement for an existing stub or fallback path. No re-architecting required.
Kill the project if, after 30 days of real Phase 0 use:
- Zero searchers exported a brief into actual outreach
- Zero advisors engaged with the shadow pack beyond "looks cool"
- Quality bar not achievable with the current skill stack + data
- Time consumption >25 hrs/week (you're in school)
- Two advisory-board candidates ghost
Pivot if:
- Demand-gen teams at advisor firms show strong interest (Jason's role becomes its own ICP)
- Searchers love the briefs but won't pay $1.5K/mo (pivot to per-brief pricing)
- Advisors love the Engagement Pack but data quality is the blocker (pivot to "human + AI" services model at $5K/pack)
Stay the course if:
- 3+ searchers actively pulling for more briefs by end of Week 4
- 1+ boutique willing to pilot the Engagement Pack on a live mandate
- Leste users opening the Deal Sourcing module >30% of MAU
- 2+ advisory-board verbal commits
| Workflow | Before this build | After this build |
|---|---|---|
| 1 brief, hand-filled JSON | ~1 hour | (legacy — still works) |
1 brief from (name, city, state) |
not possible | ~20s, ~$0.002 |
| 10 briefs from CSV | ~10 hours hand work | ~3 minutes, ~$0.02 |
| Full advisor Engagement Pack (4 polished artifacts) | not possible | ~50s, ~$0.005 |
| 5-touch cold outreach informed by brief | not possible | ~6s, ~$0.001 |
That's the unlock. Walk into a searcher conversation with their actual mandate criteria, generate 10 briefs in front of them. Walk into an advisor demo with their open mandate's project codename, generate a shadow pack live.
That's the demo. Now use it.
- Identify 3 real searcher conversations to book this week — actually go do the validation step the council unanimously demanded
- Identify 1 friendly boutique advisor — Contact A at Benchmark via the script in
ULTIMATE_BUILD_GUIDE.mdPart 7 - Stop building. The platform works. The validation is what determines whether more building matters.
When customer revenue starts coming in, open PAID_UPGRADES_ROADMAP.md and execute by tier.