-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathREADME.preview.html
More file actions
417 lines (409 loc) · 16.8 KB
/
Copy pathREADME.preview.html
File metadata and controls
417 lines (409 loc) · 16.8 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>DealBrain — Platform Overview</title>
<style>
:root {
--ink: #1a1a1a;
--ink-soft: #5a5a5a;
--line: #e0e0e0;
--accent: #1e4a8c;
--bg: #ffffff;
--bg-soft: #fafaf8;
}
@media (prefers-color-scheme: dark) {
:root {
--ink: #ebebeb;
--ink-soft: #b5b5b5;
--line: #2a2a2a;
--accent: #9ec1ff;
--bg: #161616;
--bg-soft: #1f1f1f;
}
}
body {
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue",
sans-serif;
max-width: 760px;
margin: 40px auto;
padding: 0 24px 80px;
line-height: 1.55;
color: var(--ink);
background: var(--bg);
font-size: 16px;
}
h1 { font-size: 1.9rem; border-bottom: 2px solid var(--line); padding-bottom: 8px; margin-top: 0; }
h2 { font-size: 1.35rem; margin-top: 2em; color: var(--accent); }
h3 { font-size: 1.1rem; margin-top: 1.5em; }
p, li { color: var(--ink); }
strong { color: var(--ink); }
em { color: var(--ink-soft); }
blockquote {
border-left: 3px solid var(--accent);
margin: 1.2em 0;
padding: 0.4em 1em;
color: var(--ink-soft);
background: var(--bg-soft);
}
code {
background: var(--bg-soft);
padding: 0.1em 0.35em;
border-radius: 3px;
font-size: 0.9em;
font-family: "SF Mono", Consolas, "Liberation Mono", monospace;
}
pre {
background: var(--bg-soft);
padding: 1em;
border-radius: 5px;
overflow-x: auto;
}
table {
border-collapse: collapse;
width: 100%;
margin: 1.2em 0;
font-size: 0.92rem;
}
th, td {
border: 1px solid var(--line);
padding: 8px 12px;
text-align: left;
vertical-align: top;
}
th { background: var(--bg-soft); font-weight: 600; }
hr { border: none; border-top: 1px solid var(--line); margin: 2em 0; }
/* Print preset: clean for save-as-PDF */
@media print {
body { margin: 1in; max-width: none; font-size: 11pt; }
h2 { page-break-after: avoid; }
table { page-break-inside: avoid; }
}
</style>
</head>
<body>
<h1>DealBrain — AI M&A Sourcing & Engagement Platform</h1>
<blockquote>
<p>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 <code>(name, city, state)</code> to fully styled deliverables in minutes for cents.</p>
</blockquote>
<hr />
<h2>What's in the box</h2>
<h3>Two ICPs, one shared brain</h3>
<pre><code> ┌──────────────────────────────────────────────┐
│ 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) │
└───────────────────────────┘ └─────────────────────────────┘
</code></pre>
<p>Every output is IB-grade styled (Arial, navy accents, real Word tables/numbering, no unicode bullets), follows the canonical Anthropic claude-skills <code>docx</code> + <code>xlsx</code> skill patterns, and passes the banned-phrase + confidence-tagger gates.</p>
<h3>Quality non-negotiables (machine-enforced)</h3>
<ul>
<li><strong>Banned-phrase filter</strong> — "leverage synergies", "value-add", "drive growth without a channel" etc. blocked at output time</li>
<li><strong>Confidence tagging</strong> — every inferred number carries <code>(est, conf: 0.X, src: method)</code></li>
<li><strong>Adapter priority + merge</strong> — high-confidence sources always win on field merges; no silent fabrication</li>
</ul>
<hr />
<h2>Quickstart</h2>
<pre><code class="language-powershell">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
</code></pre>
<hr />
<h2>The full workflow CLI map</h2>
<table>
<thead>
<tr>
<th>Script</th>
<th>Input</th>
<th>Output</th>
<th>Time</th>
<th>Cost (cheap mode)</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>scripts/enrich_target.py</code></td>
<td>name + city + state</td>
<td>enriched JSON + brief</td>
<td>~20s</td>
<td>~$0.002</td>
</tr>
<tr>
<td><code>scripts/batch_enrich.py</code></td>
<td>CSV of names</td>
<td>folder of briefs + summary CSV</td>
<td>~20s/row</td>
<td>~$0.002/row</td>
</tr>
<tr>
<td><code>scripts/generate_brief.py</code></td>
<td>enriched JSON</td>
<td>brief.md + .docx + .html + meta</td>
<td>~7-15s</td>
<td>~$0.001</td>
</tr>
<tr>
<td><code>scripts/batch_generate.py</code></td>
<td>folder of JSONs</td>
<td>folder of briefs + summary CSV</td>
<td>~7s/target</td>
<td>~$0.001/target</td>
</tr>
<tr>
<td><code>scripts/generate_pack.py</code></td>
<td>sell-side mandate JSON</td>
<td>4-artifact pack (md/docx/xlsx)</td>
<td>~50s</td>
<td>~$0.005</td>
</tr>
<tr>
<td><code>scripts/generate_outreach.py</code></td>
<td>target JSON + brief.md</td>
<td>5-touch outreach sequence</td>
<td>~6s</td>
<td>~$0.001</td>
</tr>
</tbody>
</table>
<p>Set <code>MODE=production</code> in <code>.env</code> to use the full LLM Council instead of cheap-mode (premium models, 20-30× cost, dramatically better quality).</p>
<hr />
<h2>Project layout</h2>
<pre><code>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
</code></pre>
<hr />
<h2>The skill library (17 SKILL.md files)</h2>
<p>Each skill is documented in <code>dealbrain/skills/<skill-name>/SKILL.md</code>:</p>
<table>
<thead>
<tr>
<th>Skill</th>
<th>Purpose</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>outreach-brief-generator</code></td>
<td>Tier 0 → 1 → 2 brief pipeline</td>
</tr>
<tr>
<td><code>engagement-pack-assembler</code></td>
<td>4-artifact advisor pack</td>
</tr>
<tr>
<td><code>cold-outreach-sequencer</code></td>
<td>5-touch outreach in operator voice</td>
</tr>
<tr>
<td><code>target-enrichment-pipeline</code></td>
<td>(name, city, state) → enriched JSON</td>
</tr>
<tr>
<td><code>confidence-tagger</code></td>
<td>"no silent estimates" enforcement</td>
</tr>
<tr>
<td><code>banned-phrase-filter</code></td>
<td>Anti-consultant-slop quality gate</td>
</tr>
<tr>
<td><code>hvac-signal-ontology</code></td>
<td>Structured strong/medium/weak signals for HVAC</td>
</tr>
<tr>
<td><code>brief-docx-renderer</code></td>
<td>IB-grade docx-js brief</td>
</tr>
<tr>
<td><code>teaser-docx-renderer</code></td>
<td>IB-grade docx-js teaser</td>
</tr>
<tr>
<td><code>cim-docx-renderer</code></td>
<td>Multi-page docx-js CIM with cover + TOC</td>
</tr>
<tr>
<td><code>outreach-docx-renderer</code></td>
<td>5-touch outreach docx with day badges</td>
</tr>
<tr>
<td><code>buyer-list-xlsx-renderer</code></td>
<td>openpyxl IB-color-coded buyer list</td>
</tr>
<tr>
<td><code>comps-xlsx-renderer</code></td>
<td>openpyxl 5-sheet financial model with formulas</td>
</tr>
</tbody>
</table>
<hr />
<h2>What's deferred (and where to find it)</h2>
<p><strong>Phase 1 build queue</strong> — see <code>PAID_UPGRADES_ROADMAP.md</code> for every paid component with cost / unlock / wiring effort:</p>
<ul>
<li>Coresignal (LinkedIn-derived succession signals) — biggest single quality jump</li>
<li>BuiltWith Pro (real field-service-software detection)</li>
<li>State HVAC license registries (FL DBPR, TX TDLR, GA CILB)</li>
<li>UCC liens / distress signals</li>
<li>Real PDF rendering (currently HTML → browser-print)</li>
<li>PPTX renderer (for pitch decks)</li>
<li>Web UI (currently CLI-only)</li>
<li>Multi-tenant Postgres (currently JSON files)</li>
<li>Affinity CRM native integration</li>
<li>Outreach.io / Smartlead sequencer integration</li>
<li>SOC 2 prep (for enterprise advisor customers)</li>
<li>Brand customization tokens</li>
</ul>
<p>Architecture is deliberately built so every deferred item is a <strong>drop-in replacement</strong> for an existing stub or fallback path. No re-architecting required.</p>
<hr />
<h2>Ship criteria (the "stop building" line per ULTIMATE_BUILD_GUIDE Part 6)</h2>
<p><strong>Kill the project if, after 30 days of real Phase 0 use:</strong>
- 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</p>
<p><strong>Pivot if:</strong>
- 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)</p>
<p><strong>Stay the course if:</strong>
- 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</p>
<hr />
<h2>The Phase 0 unlock you now have</h2>
<table>
<thead>
<tr>
<th>Workflow</th>
<th>Before this build</th>
<th>After this build</th>
</tr>
</thead>
<tbody>
<tr>
<td>1 brief, hand-filled JSON</td>
<td>~1 hour</td>
<td>(legacy — still works)</td>
</tr>
<tr>
<td>1 brief from <code>(name, city, state)</code></td>
<td>not possible</td>
<td><strong>~20s, ~$0.002</strong></td>
</tr>
<tr>
<td>10 briefs from CSV</td>
<td>~10 hours hand work</td>
<td><strong>~3 minutes, ~$0.02</strong></td>
</tr>
<tr>
<td>Full advisor Engagement Pack (4 polished artifacts)</td>
<td>not possible</td>
<td><strong>~50s, ~$0.005</strong></td>
</tr>
<tr>
<td>5-touch cold outreach informed by brief</td>
<td>not possible</td>
<td><strong>~6s, ~$0.001</strong></td>
</tr>
</tbody>
</table>
<p>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.</p>
<p>That's the demo. Now use it.</p>
<hr />
<h2>Phase 0 next moves (the build plan's call)</h2>
<ol>
<li><strong>Identify 3 real searcher conversations to book this week</strong> — actually go do the validation step the council unanimously demanded</li>
<li><strong>Identify 1 friendly boutique advisor</strong> — Contact A at Benchmark via the script in <code>ULTIMATE_BUILD_GUIDE.md</code> Part 7</li>
<li><strong>Stop building.</strong> The platform works. The validation is what determines whether more building matters.</li>
</ol>
<p>When customer revenue starts coming in, open <code>PAID_UPGRADES_ROADMAP.md</code> and execute by tier.</p>
</body>
</html>