mark/vibn-agent-runner
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(pmf): explicitly document DataForSEO aggregation api usage for extracting customer pain points from reviews

Browse Source
This commit is contained in:
mawkone
2026-05-07 22:27:30 -07:00
parent 96bacc9be4
commit 3cbce38c97
2 changed files with 16 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
docs/MARKET_RESEARCH_TOOLS_SUMMARY.md
View File

@@ -14,8 +14,9 @@ The data foundation is a highly scalable, relational model hosted in Google BigQ
## 2. MCP Tools Added (`lib/ai/vibn-tools.ts`)
### `market_research_run`
* **Purpose:** Fetches a list of real-world business leads for a specific category and location.
* **Data Source:** DataForSEO Business Listings Live API.
* **Purpose:** Fetches the exact Total Addressable Market (TAM) counts and extracts the raw lead data (emails, addresses, phones) for a specific category and location.
* **Data Source:** DataForSEO Business Listings Live API (using the `search/live` endpoint).
* **Quality Control:** Automatically applies strict filters (`is_claimed: true` and `current_status <> "closed_forever"`) to ensure only verified, active businesses are returned.
* **Guardrails:**
* Requires explicit user permission (`user_explicitly_approved: true`).
* **Geospatial Caching:** Queries BigQuery using PostGIS (`ST_DWithin`) first. If leads exist within a 20km radius of the target coordinates, it serves them for $0.00 instead of hitting the paid API.
@@ -27,6 +28,12 @@ The data foundation is a highly scalable, relational model hosted in Google BigQ
* **Dynamic Competitor Injection:** Reads the `software_category_id`, pulls all known competitors from BigQuery, and dynamically searches the target websites' source code for traces of those competitors.
* **Custom Checks:** Allows the AI to pass a `custom_checks` array of custom strings/domains to look for on the fly.
### `market_aggregate_insights`
* **Purpose:** Fetches aggregated insights for a specific market niche to uncover qualitative data before building a product.
* **Data Source:** DataForSEO Categories Aggregation Live API.
* **Output:** Returns a breakdown of sub-niches (e.g., Pediatric vs Cosmetic), the total number of businesses with/without websites (technical debt indicator), and crucially, the **Top Customer Review Topics** (e.g., "receptionist", "price", "wait time"). The AI uses these pain points to write the Value Proposition and positioning strategy.
### `market_seo_analyze`
* **Purpose:** Analyzes a competitor's domain for SEO and Google Ads metrics.
* **Data Source:** DataForSEO Labs (Domain Metrics & Ranked Keywords APIs).

11
docs/PRODUCT_MARKET_FIT_ENGINE.md
View File

@@ -12,12 +12,15 @@ When a user wants to build a product (e.g., "Software for Dentists"), the Vibn A
5. **Website Positioning:** Value propositions and wedge strategies designed explicitly to exploit competitor weaknesses.
6. **Financials & Pricing:** A calculated MRR model and disruptive pricing strategy based on local TAM and competitor costs.
## 1. Market Sizing & Lead Generation
**Goal:** Prove the market exists and give the founder their first 100 cold-outreach targets.
**Goal:** Prove the market exists, identify customer pain points, and provide the founder their first 100 cold-outreach targets.
* **Mechanism:** The AI maps the software idea to a specific Google Business Profile category (e.g., `gcid:dentist`).
* **Tooling:** Uses the **DataForSEO Business Listings API** to scrape Google Maps in a defined geographic area.
* **Output:** A structured CSV/JSON of real-world businesses, including their names, addresses, ratings, and scraped email addresses.
* **Data Co-op Model:** Searches are charged via credits/micro-transactions. Results are cached in Vibn's Postgres database (`market_leads`). Over time, Vibn builds a proprietary, zero-cost database of every SMB in North America.
* **Tooling:** Uses two distinct DataForSEO Business Listings APIs:
1. **`search/live` API:** Used to fetch the exact Total Addressable Market (TAM) counts and extract the raw lead data (emails, addresses, phones). Crucially, this API is passed strict filters (e.g., `["address_info.country_code", "=", "CA"]` and `["work_time.work_hours.current_status", "<>", "closed_forever"]`) to guarantee accurate national counts and exclude dead businesses.
2. **`categories_aggregation/live` API:** Used to perform deep qualitative analysis. This endpoint aggregates thousands of Google Reviews to surface the **Top Customer Pain Points** (e.g., "receptionist", "price", "long wait") and break the market down into specific sub-niches (e.g., Cosmetic Dentistry vs. Pediatric Dentistry).
* **Output:** A structured JSON of real-world businesses with extracted emails, alongside a summary of what patients/customers complain about most frequently in that market.
* **Data Co-op Model:** Searches are charged via credits. Results are cached in BigQuery (`vibn_market_data`). Over time, Vibn builds a proprietary, zero-cost database of every SMB in North America.
## 2. Competitor Identification & Website Teardown
**Goal:** Understand what the market leaders are doing and how to beat them.