Skip to main content

Get Focal Harvest Running in 30 Seconds

You can have Focal Harvest installed and producing your first research report in under a minute. This page covers installation, launching the TUI, running a sweep programmatically, and verifying everything works with the test suite.

Contents​

Requirements​

  • Python 3.12 or higher
  • No GPU, Docker, or database required

Install Dependencies​

Run the platform-independent installer. It sets up core requirements and automatically attempts to install optional bypass enhancements like curl_cffi:

python install.py

If you prefer a standard pip install without the optional extras:

pip install -r requirements.txt

Both methods work. The installer is recommended for first-time setup because it handles platform-specific edge cases automatically.

Launch the Interface​

Start the interactive Terminal User Interface:

python main.py

From the TUI, select Option 1 to run a single research sweep, Option 2 to start a monitoring daemon, or Option 3 to configure your API keys and settings. No API keys are needed to run your first sweep — offline mode activates automatically.

Run a Sweep Programmatically​

For automation scripts and custom pipelines, you can call the scraping and synthesis stages directly:

from scraper import search_duckduckgo, scrape_urls_concurrently
from analyzer import synthesize_topics

# 1. Search for a query
results = search_duckduckgo("Gemini 1.5 Flash vs Pro", max_results=5)
urls = [r["url"] for r in results]

# 2. Scrape target pages concurrently
scraped_data = scrape_urls_concurrently(urls)

# 3. Synthesize findings into a structured Markdown report
report = synthesize_topics(
    scraped_data,
    query="Gemini 1.5 Flash vs Pro",
    spec_topic="pricing and performance comparisons"
)

print(report)

The report is returned as a Markdown string and automatically saved to reports/. If no API keys are configured, synthesize_topics falls back to the offline PositionRank ranker.

Run the Test Suite​

Verify the installation and mock request flows with the unit test suite:

python -m unittest discover -s tests

All tests should pass on a clean install. If any fail, check that your Python version is 3.12+ and that all dependencies installed correctly.

Next: Add API Keys​

Focal Harvest works offline out of the box, but connecting an AI provider upgrades your summaries significantly. See Configuration → for how to add Gemini, OpenAI, or Claude API keys — and how to set up Discord or Telegram webhook alerts.