Skip to content

README.md

Latest commit

 

History

History
225 lines (146 loc) · 5.66 KB

README.md

File metadata and controls

225 lines (146 loc) · 5.66 KB
Raw

Funnel Vision

Funnel Vision is an AI-powered landing page teardown tool.

It captures your page, analyzes conversion elements with Claude using a FLOW framework, overlays visual bounding-box diagnostics, generates a PDF teardown report, and provides an in-app follow-up chatbot for implementation questions.

What It Does

  1. Scrapes a landing page and captures a full-page screenshot.
  2. Extracts text and button bounding boxes from the DOM.
  3. Sends visual + structural context to Claude for conversion analysis.
  4. Produces a visual PDF report with color-coded overlays.
  5. Shows grouped issue insights in Streamlit.
  6. Enables a contextual AI chat assistant after analysis.

FLOW Framework Used

The analysis categorizes issues into:

  1. Friction
  2. Legitimacy
  3. Offer Clarity
  4. Willingness to Buy

Tech Stack

  1. UI: Streamlit
  2. Browser automation and capture: Playwright + AgentQL
  3. LLM analysis and chat: Anthropic Claude via LangChain
  4. Report rendering: Pillow + FPDF2
  5. Packaging and dependency management: uv / pip

Project Structure

  1. app.py: Streamlit app entry point, full pipeline orchestration, and post-analysis chat UI.
  2. src/scraper.py: Browser automation, screenshot capture, and DOM box extraction.
  3. src/analyze_local.py: Claude FLOW analysis and JSON output creation.
  4. src/pdf_generator.py: Builds report inputs from scraped + analyzed artifacts.
  5. src/report_generator.py: Draws overlays/legend and writes final PDF.
  6. src/main.py: Script-based pipeline entry point (non-UI).
  7. src/delete_screenshots.py: Cleanup helper for screenshot artifacts.

Prerequisites

  1. Python 3.13+
  2. One of:
    1. uv (recommended)
    2. pip + virtual environment
  3. API keys:
    1. ANTHROPIC_API_KEY (required for analysis and assistant chat)
    2. AGENTQL_API_KEY (recommended/required for AgentQL queries, depending on your account/setup)

Environment Variables

Create a .env file in the project root:

ANTHROPIC_API_KEY=your_anthropic_key
AGENTQL_API_KEY=your_agentql_key

Notes:

  1. If ANTHROPIC_API_KEY is missing, analysis and chat cannot run.
  2. If AgentQL is not authenticated/configured, scraping query steps may fail.

Installation

Option A: uv (recommended)

uv sync

Option B: pip

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m playwright install chromium

Run the App (Primary Workflow)

uv run streamlit run app.py

Then open the local URL shown by Streamlit (usually http://localhost:8501).

In-App Flow

  1. Enter a landing page URL.
  2. Click Analyze Funnel.
  3. Wait for scrape + Claude analysis + PDF generation.
  4. Review:
    1. Visual teardown preview (left)
    2. Structured Claude FLOW issues (right)
    3. AI CRO Assistant chat (below report section)
  5. Download funnel_teardown_report.pdf.

Script Workflow (No Streamlit)

You can also run the pipeline from the terminal:

uv run python src/main.py "https://example.com"

If no URL is provided, src/main.py uses its internal default URL.

Output Artifacts

Generated files in project root:

  1. scrape_results.json: raw scrape payload, text/button boxes, screenshot paths.
  2. flow_analysis.json: Claude output with structured FLOW issues.
  3. teardown_report.pdf: final visual report with overlays and legend.

Intermediate folder:

  1. page_screenshots/: captured screenshots used during processing.

Cleanup:

  1. src/delete_screenshots.py clears screenshot files after successful runs.

Bounding Box Visualization

The PDF overlay currently uses:

  1. Scored issue boxes (selected by Claude): heatmap colors by score.
  2. Non-selected boxes: green highlight.
  3. A legend in the top-right area of each report image to explain colors.

Assistant Chat Behavior

The Streamlit chatbot:

  1. Is available after a successful analysis.
  2. Uses the current flow_analysis.json context plus recent chat turns.
  3. Resets chat history when a new analysis result is generated.

Common Commands

Run app:

uv run streamlit run app.py

Run script pipeline:

uv run python src/main.py "https://example.com"

Remove screenshots manually:

uv run python src/delete_screenshots.py

Troubleshooting

1) Missing API key errors

Symptom:

  1. Analysis fails, or chat says ANTHROPIC_API_KEY is missing.

Fix:

  1. Add ANTHROPIC_API_KEY to .env.
  2. Restart Streamlit.

2) Browser / Playwright issues

Symptom:

  1. Scraper fails to launch Chromium.

Fix:

  1. Run: python -m playwright install chromium
  2. On Linux/containers, install system libraries listed in packages.txt.

3) AgentQL query failures

Symptom:

  1. Scrape step fails around AgentQL calls.

Fix:

  1. Ensure AGENTQL_API_KEY is configured.
  2. Re-run after validating network access.

4) No report generated

Symptom:

  1. teardown_report.pdf not created.

Fix:

  1. Verify page_screenshots contains at least one PNG.
  2. Confirm flow_analysis.json exists and contains issues array.

Security and Privacy Notes

  1. Page screenshots and extracted on-page text are sent to external AI services during analysis.
  2. Do not run this tool against sensitive/private pages unless you are authorized.
  3. Review vendor data-handling policies for compliance requirements.

Development Notes

  1. requirements.txt is generated from pyproject.toml.
  2. The Streamlit app currently auto-attempts Playwright Chromium install at startup.
  3. tests directory currently has no active test suite.

License

No license file is currently present in this repository.