GortexAI/franco

Maintainer? Show your league in your README

Card: your league's emblem, from Copper to Legendary

[![bestofgithub](https://bestofgithub.dev/badge/GortexAI/franco.svg?style=card)](https://bestofgithub.dev/repo/GortexAI/franco)

Flat: fits beside your other badges

[![bestofgithub](https://bestofgithub.dev/badge/GortexAI/franco.svg)](https://bestofgithub.dev/repo/GortexAI/franco)

Loading README…

Agent	What it does
Scout	Scores and personalizes prospects. Searching, website reading and email resolution are plain Python.
Writer	Drafts sequences with the model (generated), renders approved copy with no model (approved copy), or places accounts in funnels and writes email 1 from the funnel's brief (raad).
Sender	Stages each email in the outbox with a send time, then sends due, approved items with human-like pacing, the daily cap and the pre-send gate.
Handler	Reads replies, removes quoted text, classifies intent, stops sequences, records opt-outs, detects bounces, and queues responses through the outbox.
Analyst	On idle cycles, writes pipeline stats to `data/analytics.json`.

Kind	One row is	Required columns	Used by
`accounts`	a researched account: one buyer, the campaign they get, and the sourced fact behind it	`company, domain, campaign, first_name, last_name, title, email, observation, source_url, source_date`	approved copy, raad
`contacts`	a company, optionally with a person at it	`company, domain`	generated, raad
`suppressions`	an email address or a whole domain never to contact	`value` (an address or a domain)	everything

Source	Cost	Free tier
OpenStreetMap (default)	free	unlimited. Thin coverage; a trial source.
DataForSEO Business Listings	$0.372 / 1k businesses	$1 credit
DataForSEO SERP	$0.0018 / search at depth 30	$1 credit + sandbox
Serper	~$0.30–1.00 / 1k	2,500 free

File	What it holds	Sensitive?
`franco.db`	The SQLite database: every company, person, email address, observation, email sent, reply, suppression, setting and decision	Yes: personal data about the people you contact
`gmail_token.json`	The Gmail OAuth refresh token from `franco gmail auth`	Yes: treat it like a password; it can send as you
`franco.log`	The heartbeat log when Franco is started from the dashboard	Somewhat: email addresses appear in it
`franco.pid`	The process id of a dashboard-started `franco run`	No
`analytics.json`	The analyst's latest pipeline report	Somewhat

File	What it is
`pyproject.toml`	The version ranges `pip install -e .` accepts
`requirements.in`	The same direct dependencies and ranges
`requirements.txt`	Generated. Every package, including the ones those depend on, pinned to an exact version with hashes. Docker installs exactly this.

Franco