cross-st 0.1.0

AI reports. Cross-examined. Research reports from multiple AI providers, fact-checked against each other.

Cross

AI reports. Cross-examined.

Cross is released under the MIT License. Free for personal, academic, and open-source use. Commercial organizations are encouraged to contact us for a commercial license — see COMMERCIAL_LICENSE.md.

Cross is an open-source command-line tool that generates research reports using five AI (more or less) simultaneously, then cross-checks each report against all the others. The result is a cross-product fact-check matrix — every AI evaluating every other AI — so you can see exactly where they agree, where they diverge, and which claims don't hold up. Reports publish directly to Discourse. It's research-grade, keyboard-first, and built for people who want to publish accurate content fast.

Cross-check before you publish.

---

Features

• Multi-AI generation — submit the same prompt to multiple AI providers simultaneously
• Cross-product fact-checking — each AI fact-checks every other AI's report (5×5 matrix)
• Analysis and plots — reading metrics, score heatmaps, bar charts
• Discourse publishing — post stories, fact-checks, and audio to any Discourse site
• Text-to-speech — generate and post MP3 audio via a local TTS server
• API response cache — avoid redundant API calls; replay results instantly
• Interactive CLI — menu-driven st command or direct st-* commands

---

AI Providers

Provider	Model
Anthropic	claude-opus-4-5
xAI	grok-4-latest
OpenAI	gpt-4o
Perplexity	sonar-pro
Google	gemini-2.5-flash

---

Quick Start — Users

1. Install Homebrew (macOS — skip if already installed)

Homebrew is the standard macOS package manager. If you don't have it:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install pipx

pipx installs Python CLI tools into isolated environments and puts them on your PATH — no virtualenv management, no version conflicts.

# macOS
brew install pipx && pipx ensurepath

# Linux — Debian / Ubuntu
sudo apt install pipx && pipx ensurepath

# Linux — Fedora / RHEL
sudo dnf install pipx && pipx ensurepath

Restart your terminal after pipx ensurepath so the new PATH takes effect.

3. Install Cross

pipx install cross-st              # no TTS audio
pipx install "cross-st[tts]"       # with text-to-speech (st-speak, st-voice)

Both work on Python 3.10–3.13. No version juggling required. See README-TTS-audio.md if you want MP3 audio output.

4. Set up API keys

st-admin --setup

The wizard prompts for each API key and saves them to ~/.crossenv. At minimum you need one provider. Google Gemini is free with no credit card required — a good place to start.

5. Write your first report

st-new my_topic.prompt            # create a prompt from the template, opens in editor
st-new --bang my_topic.prompt     # generate with all AI, then open the interactive menu

---

Quick Start — Developers

Developers work from a cloned repo with an editable install. Two repos are needed: the main cross repo and a separate cross-story repo for story containers.

1. Install Homebrew (macOS — skip if already installed)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install prerequisites

# macOS
brew install python@3.11 ffmpeg aspell grip

# Linux — Debian / Ubuntu
sudo apt install python3.11 python3.11-venv ffmpeg aspell
pip install grip

# Linux — Fedora / RHEL
sudo dnf install python3.11 ffmpeg aspell
pip install grip

Why Python 3.11? Cross runs on Python 3.10, 3.11, 3.12, and 3.13 — all four pass the full import test (tests/test_tts_stack.py). Python 3.11 is the recommended dev baseline because requirements.txt was built and pinned on 3.11. Using 3.12 or 3.13 works fine; 3.11 is just the known-good reference for debugging package conflicts.

Platform support: macOS and Linux are fully supported. Windows requires WSL2 — see README_FAQ.md.

3. Clone both repos

git clone https://github.com/b202i/cross.git
git clone https://github.com/b202i/cross-story.git
ln -s ~/github/cross-story ~/github/cross/story
cd cross

4. Create the virtual environment and install

python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .

5. Configure API keys

cp .env.example .env
# open .env and fill in at least one API key

See README_opensource.md for provider sign-up links and Discourse configuration. API keys live in .env — never commit this file.

6. Generate your first report

st-new my_topic.prompt            # create a prompt from the template, opens in editor
st-new --bang my_topic.prompt     # generate with all AI, then open the interactive menu

---

Typical Workflow

Generate → View → Edit → Analyze → Post

1. st-new — create a prompt from a template
2. st-bang — generate reports from all 5 AI in parallel
3. st-prep — extract title, text, markdown, and spoken versions
4. st-fact / st-cross — fact-check one story or the full 5×5 matrix
5. st-analyze — generate a cross-product summary report
6. st-edit — review and refine in vim with optional browser preview
7. st-post — publish to Discourse with optional MP3 audio

All steps are also accessible through the st interactive menu.

---

Command Reference

Command	Purpose
st	Interactive menu — accepts .json or .prompt; generates .json if needed
st-new	Create a prompt from template; optionally generate with --bang or --st
st-gen	Generate a story from a prompt with one AI
st-bang	Generate stories from all AI in parallel
st-prep	Process raw AI output into title / markdown / text / spoken
st-merge	Merge multiple AI stories into one
st-edit	Edit or browser-preview a story
st-ls	List stories and fact-checks in a container
st-find	Search for keywords (with wildcards and boolean operators) in titles, prompts, and stories
st-fact	Fact-check a story with one AI
st-cross	Cross-product fact-check — all stories × all AI
st-analyze	Generate a cross-product analysis report
st-speed	Analyze AI performance and speed from timing data
st-fix	Revise a story using its fact-check results
st-read	Show reading-level metrics
st-plot	Plot cross-product scores
st-heatmap	Score heatmap across AI combinations
st-post	Post story (and optional audio) to Discourse
st-speak	Generate TTS audio for a story
st-voice	Manage TTS voice selection
st-rm	Remove a story or fact-check from a container
st-cat	Print raw JSON container contents

---

Project Structure

cross/
├── cross_ai/               # Python package — all runtime code lives here
│   ├── st.py               # Interactive menu (command builder)
│   ├── st-*.py             # Individual CLI commands (28 tools)
│   ├── ai_handler.py       # AI dispatcher (shim → cross-ai-core)
│   ├── base_handler.py     # Abstract base class shim → cross-ai-core
│   ├── discourse.py        # Discourse API client
│   ├── mmd_*.py            # Support modules (processing, plotting, voice, util)
│   ├── commands.py         # Entry-point dispatch for pyproject.toml
│   └── template/           # Prompt templates for st-new
├── tests/                  # Test suite
├── docs/wiki/              # GitHub Wiki source (auto-built)
├── pyproject.toml          # Package metadata and entry points
├── requirements.txt        # Pinned Python dependencies
├── .env                    # API keys and Discourse credentials (never commit)
└── tmp/                    # Transient coordination files (gitignored)

---

Further Reading

File	Contents
README_install.md	Full install guide for a new machine (clone, venv, symlinks, keys)
README-TTS-audio.md	TTS audio setup — Python versions, platform install, Piper server, voices
README_post.md	Publishing guide — Discourse, GitHub Gist, Bluesky, Reddit, X.com
README_ui.md	Full menu reference and UI conventions
README_FAQ.md	Frequently asked questions
ERROR_QUICK_REFERENCE.md	API errors and solutions — quota limits, rate limits, troubleshooting
README_opensource.md	Setup, API keys, Discourse configuration
README_devel.md	Developer notes and architecture
README_cross_product.md	Cross-product analysis deep dive
README_speed_comparison.md	AI performance metrics and speed comparison strategy
README_testing.md	Regression testing strategy and best practices
TESTING_QUICKSTART.md	Run tests quickly — commands and current status

---

License

MIT — free for personal, academic, and open-source use. See LICENSE for the full text.

Organizations deploying Cross in commercial or government contexts are encouraged to reach out for a licensing and support agreement. See COMMERCIAL_LICENSE.md.

For the full licensing strategy and roadmap see README_license.md.

---

AI reports. Cross-examined.
GitHub: github.com/b202i/cross