astra-signal-outbound

KO | EN

gitlite — search

#chatbot #mysql #privacy #rag #cli #ios #github #data-science #terminal #html

astra-signal-outbound

(★ 9)

Find companies with a reason to talk this week. GPT-6 Astra researches recent signals, Python verifies the evidence and ranks accounts, you review the drafts in Codex.

File Explorer

ZIP Download

- config.toml
- - tests.yml
- EVIDENCE.md
- SIGNALS.md
- VALIDATION.md
- fictional-demo.md
- live-run.md
- research.json
- test_bot.py
.gitignore
AGENTS.md
bot.py
core.py
fixtures.py
LICENSE
profile.example.json
README.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

**Find companies with a reason to talk this week. Check the buyer, read the evidence, and draft the first message in Codex.**

Built for [Nicolas Finet](https://x.com/nifinet). Give the bot your offer and ideal
customer profile (ICP). GPT-6 Astra researches recent signals on the public web;
the Python runner checks the returned evidence, ranks qualifying accounts, and
writes a brief you can review in the same Codex conversation.

A funding announcement is a starting point. The useful question is what the
company plans to do with the money, whether you help with that work, and who owns
it. Each shortlisted account needs that connection, with sources attached.

> For ongoing monitoring, enriched leads and delivery into your sales tools,
> [max at yourmax.ai](https://yourmax.ai) takes the workflow further.

**Python 3.10+ · GPT-6 Astra · MIT licensed · No Python packages to install**

## Contents

- [What you get](#what-you-get)
- [Try the offline demo](#try-the-offline-demo)
- [Set up your first live run](#set-up-your-first-live-run)
- [Use it inside Codex](#use-it-inside-codex)
- [Choose your signals](#choose-your-signals)
- [How qualification works](#how-qualification-works)
- [Review, record, repeat](#review-record-repeat)
- [Command reference](#command-reference)
- [Repository map](#repository-map)
- [Troubleshooting](#troubleshooting)
- [Validation and data handling](#validation-and-data-handling)
- [When to move to max](#when-to-move-to-max)

## What you get

Each selected lead comes with:

- **The company and buyer:** industry, country, reported headcount or range,
  buyer name, role and profile link.
- **The reason to contact them now:** a dated signal, its source, supporting
  evidence and an explanation of how your offer could help.
- **Two first-message drafts:** an email of up to 130 words and a LinkedIn
  message of up to 300 characters. These are this repository's limits.
- **The reasons to hesitate:** uncertainties, held candidates and research
  coverage, alongside the shortlist.

```mermaid
flowchart LR
    P["Your offer and ICP"] --> A["Astra: research and draft"]
    W["Live public sources"] --> A
    E["Optional supplied evidence"] --> A
    A --> G["Python: evidence checks and ranking"]
    S[("Local history and exclusions")] --> G
    G --> B["Brief: selected and held accounts"]
    B --> R["You review sources and messages"]
    B -->|"Selected events after a normal run"| S
```

The bot researches when you run it. It has no sending connector, email-address
lookup or built-in monitoring service. Private intent requires your supplied
records. A run can return fewer leads than requested, including zero.

## Try the offline demo

Extract the ZIP and open a terminal in the `astra-signal-outbound` folder, the
one containing `bot.py`. Run:

```bash
python3 bot.py demo
```

You need only Python. No Codex login, model usage or network connection is involved.
Expected summary:

```text
1 selected, 4 held. Nothing sent.
```

Open `.local/demo/reports/latest.md`. This is a shortened view of the
**fictional fixture**, with invented names and events:

| Field | Demo output |
|---|---|
| Company | Fictional Harbour Software; GB; 75 employees; B2B software |
| Buyer | Fictional Morgan, Head of Marketing |
| Signal | New-segment product launch, supported by a demand-generation vacancy |
| Why now, hypothesis | The new segment may need a dedicated conversion path |
| Score | 92/100 |
| Held | Stale signal, wrong geography, missing buyer, second candidate from the same company |

The email opens with the observation and a question:

> Hi Morgan, your launch announcement mentions a new customer segment. Are you
> giving that audience its own landing page?

The [full demo brief](examples/fictional-demo.md) includes both drafts. The demo
proves the local workflow; it does not measure live lead quality or use Astra.

## Set up your first live run

### 1. Check your prerequisites

| Requirement | Check |
|---|---|
| Python 3.10 or newer | `python3 --version` |
| Current Codex CLI available in your terminal | `codex --version` |
| Codex authentication | `codex login status` |
| Account access to GPT-6 Astra and available usage | Confirm access in Codex; the first live run verifies it |

If you need Codex, the npm installation route is:

```bash
npm install -g @openai/codex
codex login
```

That installation route requires Node.js and npm. Other installation options are
in the [official Codex CLI guide](https://learn.chatgpt.com/docs/cli).
If Codex is already installed and signed in, skip these commands.

With [ChatGPT sign-in](https://learn.chatgpt.com/docs/auth), you do not need a
separate OpenAI API key. You also do not need a max account to run this repository.
The code is free under MIT; model usage and any third-party data costs are separate.
[Astra availability](https://learn.chatgpt.com/docs/models) depends on your account
and rollout. The runner explicitly uses `gpt-6-astra` and never substitutes another model.

```bash
python3 bot.py doctor
```

`doctor` checks the installed CLI's required flags, authentication and any existing
profile. It does not make a model call or prove that your account can use Astra.
This release was tested with Codex CLI 0.153.0 on macOS.

### 2. Give it a specific offer

```bash
python3 bot.py init
```

Answer the prompts for your company, website, offer, industries, country codes,
employee range, buyer roles and a useful next step. This creates `profile.json`.
If the file already exists, edit it directly; `init` will not overwrite it.

For example, a website agency could use this **illustrative** brief:

> We build conversion-focused websites for B2B software companies. Target UK
> companies with 20–200 employees and a marketing decision-maker. Look for a
> recent launch or expansion that creates a specific page to review. Offer a
> short review of that page.

Then edit `profile.json` where needed:

| Setting | What to put there |
|---|---|
| `proof_points` | Only results or customer facts you can substantiate. Leave `[]` if you have none. |
| `signal_types`, `signal_keywords` | The events and terms relevant to this offer; see the catalog below. |
| `excluded_domains` | Customers, competitors or other exclusions as bare lowercase domains. |
| `max_age_days`, `max_leads` | Default: a 14-day window and at most 8 selected accounts. |
| `minimum_score` | Default: 65. A high score never overrides a failed qualification check. |
| `contact_cooldown_days` | Default: 90 days after you record a company as contacted. |

Use [profile.example.json](profile.example.json) as a field reference. Its
placeholder website and `configured: false` prevent it from running as a real profile.

### 3. Run a small first search

```bash
python3 bot.py run --max-leads 5 --days 14
```

Allow several minutes. The timeout is 900 seconds by default; change it with
`--timeout`. These command-line overrides apply to this run without editing your
saved profile.

A successful run writes:

| File | What to read |
|---|---|
| `.local/reports/latest.md` | The latest brief: selected leads, drafts, held reasons and queries |
| `.local/reports/latest.json` | The same report as structured data |
| `.local/runs/<run-id>/` | Archived report, original research JSON, prompt, schema and Codex log |

**What good looks like:** you can open the source, confirm what changed, and
explain why this buyer might care about your offer.

**Where it breaks:** a broad offer produces broad guesses. Tighten the job you
solve before widening the search. A missing buyer or unverifiable event belongs
in the held list.

## Use it inside Codex

Open the extracted folder as a local project in Codex and select **GPT-6 Astra**.
The same Python and CLI prerequisites apply. Or start a terminal session there:

```bash
codex --model gpt-6-astra
```

Paste this, replacing the brackets with your business details:

```text
Read AGENTS.md and README.md. Set up my signal-based outbound profile.
I help [buyer] with [offer]. We target [industries], [countries] and
[employee range]. Our useful next step is [CTA]. Ask for missing details.
Do not invent proof points. Run the included bot for up to five leads
from the last 14 days. Read the resulting brief and show me the sources,
why-now hypotheses, drafts and held reasons here.
```

[AGENTS.md](AGENTS.md) tells Codex how to configure the profile, run the bot and
read its actual output. The inner research invocation always selects Astra,
uses live search, disables shell tools and ignores user configuration for that
stage. Your interactive Codex session remains separate.

The supported executable workflow is local Codex/CLI. Uploading the ZIP into an
ordinary ChatGPT conversation does not install the Python runner or its local history.

## Choose your signals

The [signal catalog](docs/SIGNALS.md) documents **25 named families**: 19 public
research families and 6 families requiring supplied data, plus an `other` category.
This is a research catalog; each run searches a subset and reports its coverage.

| Group | Examples | Evidence needed |
|---|---|---|
| Company movement | Funding, leadership, launches, expansion, acquisitions, partnerships, contract wins | A dated event or announcement tied to the target company |
| Operational changes | Hiring, reposted jobs, pricing, technology, website changes, compliance | Dated observations; changes need evidence of what changed |
| Expressed priorities | Agency searches, public business complaints, competitor changes, content and events | An attributable business fact and a specific connection to your offer |
| Supplied intent | Pricing visits, repeat visits, content or competitor engagement, CRM reactivation, review intent | Your permitted source records with dates and stable IDs |

Smart combinations make the research question more specific:

- **Launch + relevant hiring:** is a new audience creating work the team is staffing for?
- **Expansion + a documented language gap:** would a local-language page help the announced market entry?
- **Competitor retirement + a verified customer relationship:** is there a migration problem your offer addresses?

These are hypotheses to investigate. The catalog includes ten combinations and
the evidence each needs. Astra assesses whether signals are independent and
relevant; the code does not prove that interpretation.

To add your own analytics, CRM or intent records:

```bash
python3 bot.py run --evidence /path/to/evidence.json
```

Use the exact JSON format in [docs/EVIDENCE.md](docs/EVIDENCE.md), with at most 200
records. This adds evidence to a live Astra run. It is not an offline import or a
prebuilt provider connector. Without supplied records, those six families are
unavailable and research continues on public sources.

## How qualification works

The runner checks the returned fields before ranking. It holds accounts with
unsupported fit, missing buyer details, stale or future signals, weak offer
relevance, exclusions, repeated events or invalid drafts.

Company size needs a source Astra reports opening. A returned range qualifies
only when the whole range fits your ICP. A point count supplied together with a
range is held as ambiguous. Astra is instructed to preserve sourced ranges;
the code cannot prove that it read the page correctly.

Accounts that pass receive this **100-point heuristic**:

| Component | Points |
|---|---:|
| ICP fit | 40 |
| Buyer-role fit | 15 |
| Recency within your chosen window | Up to 20 |
| Offer relevance | Up to 20 |
| A second distinct, recent signal type | 5 |

The threshold lives in `profile.json`; the weights live in [core.py](core.py).
A score of 92 is not a 92% chance of buying. Astra supplies the industry, role
and relevance judgments. The runner validates structure and applies rules to
those judgments; source truth and interpretation still need your review.

## Review, record, repeat

Before using a draft, check the event date, current buyer role and offer connection.
Keep the observation separate from the hypothesis. Edit the message if it implies
budget, buying intent or a relationship the evidence does not establish.

After manually contacting a company, record it locally. Replace `example.com`
with the actual company domain:

```bash
python3 bot.py feedback example.com --status contacted --note "Sent manually"
```

Use `irrelevant` or `do-not-contact` for a persistent hold. `qualified` removes a
feedback-based hold, but does not clear already-seen events. Feedback changes
eligibility; it does not train the model or automatically tune the score.
See [all suppression rules](docs/EVIDENCE.md#feedback-and-suppression).

The runner selects at most one lead per company per run. An event is remembered
by **company domain + primary signal type + event date**, so same-day events of
one type count as one opportunity. Selected events enter history after reports
are written; failed research does not mark them seen. A different event at the
same company can qualify later unless you suppress the company.

To inspect a live brief without marking its selected events seen:

```bash
python3 bot.py run --max-leads 5 --days 14 --dry-run
```

**`--dry-run` still uses Astra and live web search, consumes usage, and writes
reports.** It only skips recording selected events in history. Use `demo` for
the offline path.

For a recurring routine, schedule the same run command with the project directory,
Python and authenticated Codex available. Keep using the same state directory.
The host must be awake; concurrent runs sharing state are rejected. Separate
client profiles should use separate `--state-dir` paths so their histories do not mix.

## Command reference

Run these from the folder containing `bot.py`.

| Command | Purpose |
|---|---|
| `python3 bot.py doctor` | Check CLI, authentication and an existing profile |
| `python3 bot.py init` | Create your profile interactively |
| `python3 bot.py run` | Research using the saved profile |
| `python3 bot.py run --max-leads 5 --days 14 --timeout 900` | Override this run's size, window and timeout |
| `python3 bot.py run --evidence /path/to/evidence.json` | Add supplied records to live research |
| `python3 bot.py run --dry-run` | Generate a live report without marking selected events seen |
| `python3 bot.py demo` | Run the fictional offline example |
| `python3 bot.py feedback example.com --status contacted` | Record contact and start the local cooldown |
| `python3 -m unittest discover -s tests -v` | Run the standard-library test suite |
| `python3 bot.py run --help` | Show all run options, including `--profile` and `--state-dir` |

## Repository map

```text
astra-signal-outbound/
├── README.md                 setup, operation and review
├── AGENTS.md                 instructions for the interactive Codex session
├── bot.py                    profile setup, research invocation and commands
├── core.py                   evidence checks, ranking, history and rendering
├── fixtures.py               fictional offline candidates
├── profile.example.json      offer and ICP field reference
├── .codex/config.toml        Astra model and live-search defaults
├── schemas/research.json     structured research output contract
├── docs/
│   ├── SIGNALS.md            all signal types and ten combinations
│   ├── EVIDENCE.md           supplied records, feedback and suppression
│   └── VALIDATION.md         release checks and their limits
├── examples/
│   ├── fictional-demo.md     full offline output
│   └── live-run.md           reviewed live-run excerpt
├── tests/test_bot.py         qualification, state and failure-path tests
├── .github/workflows/tests.yml
├── .gitignore
└── LICENSE
```

Your `profile.json` and `.local/` reports, logs and SQLite history are created
when you use the bot. They are excluded from Git and the distributed ZIP.

## Troubleshooting

| Symptom | Next step |
|---|---|
| `codex` not found | Install the CLI and reopen your terminal. The desktop app alone does not guarantee a `codex` command on your PATH. |
| CLI lacks a required flag | Update Codex using your installation method, then rerun `doctor`. |
| Authentication or Astra access error | Run `codex login status`; sign in if needed and check account model access. Read the failed run's `codex.log`. No fallback model is used. |
| Profile rejected or already exists | Edit `profile.json`, then run `doctor`. Use real business details and two-letter country codes such as `GB` and `US`. |
| Zero qualifying leads | Read held reasons, queries and research limits. Missing evidence may explain the result; widening the ICP is useful only if you serve those companies. |
| Timeout or malformed research output | Read `.local/runs/<run-id>/codex.log`. Try a smaller search; increase `--timeout` if needed. A previous `latest.md` may still exist, so check its date and the run's completion message. |
| Active lock after a crash | Confirm the old process has stopped before removing `.local/run.lock`, or the lock in your custom state directory. |
| A company reappears | Check whether it has a new event and whether you recorded `contacted`. Keep the same `--state-dir` between runs. |

## Validation and data handling

The release audit passed **39 tests**, the offline demo and a fresh live Astra
run. That live run selected one company and produced both drafts. It was a small
execution check, not a lead-quality or conversion benchmark. See
[validation notes](docs/VALIDATION.md) for that audit and its limits. An
[earlier live output excerpt](examples/live-run.md) shows the brief's format.

Local validation used macOS, Python 3.13.4 and Codex CLI 0.153.0. Linux CI for
Python 3.10/3.13 is configured; remote GitHub Actions was not run for this release.

Your profile and supplied evidence are sent to Codex for research. Keep secrets
out of them. `.local/`, `profile.json` and `.env` files are ignored by Git;
Codex manages authentication outside this repository. Logs contain your business
context and research, so keep them private.
The starter does not send lead data to max. Its max invitation appears in the
operator brief and is kept out of prospect-facing drafts.

## When to move to max

Use this repository to research your market, inspect the evidence and refine
what makes an account worth contacting. When maintaining the searches, collecting
signals and moving leads into your sales tools becomes the recurring work,
**[try max](https://yourmax.ai)**.

| Job | This repository | max |
|---|---|---|
| Find fresh signals | Public-web research each time you run it | Ongoing monitoring and daily lead delivery |
| Match your market | Your saved offer and ICP, with local qualification checks | ICP filtering with the source context attached |
| Prepare contact details | Buyer and company research; no email lookup | Profile enrichment, including email where available |
| Hand leads to your team | Local Markdown and JSON briefs | Connections to sales tools, CRM and Slack workflows |

See the [product and integrations](https://yourmax.ai/) and
[current signal catalog](https://yourmax.ai/product/signals/) for availability.
The repository's research categories and max's supported signals are separate
catalogs. You can use this starter independently; a max account is optional.

---

Built for [Nicolas Finet](https://x.com/nifinet). [MIT licensed](LICENSE).
Read it, adapt it, and use it for your own market.

astra-signal-outbound

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README