crossai-cli 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- crossai_cli-0.1.0/LICENSE +26 -0
- crossai_cli-0.1.0/PKG-INFO +327 -0
- crossai_cli-0.1.0/README.md +276 -0
- crossai_cli-0.1.0/cross_ai/__init__.py +0 -0
- crossai_cli-0.1.0/cross_ai/ai_error_handler.py +15 -0
- crossai_cli-0.1.0/cross_ai/ai_handler.py +22 -0
- crossai_cli-0.1.0/cross_ai/ai_url.py +89 -0
- crossai_cli-0.1.0/cross_ai/base_handler.py +3 -0
- crossai_cli-0.1.0/cross_ai/commands.py +54 -0
- crossai_cli-0.1.0/cross_ai/cross_stones/cross-stones-10.json +57 -0
- crossai_cli-0.1.0/cross_ai/cross_stones/domains/creative_media.prompt +18 -0
- crossai_cli-0.1.0/cross_ai/cross_stones/domains/customer_service.prompt +12 -0
- crossai_cli-0.1.0/cross_ai/cross_stones/domains/data_analytics.prompt +18 -0
- crossai_cli-0.1.0/cross_ai/cross_stones/domains/education_learning.prompt +18 -0
- crossai_cli-0.1.0/cross_ai/cross_stones/domains/finance_business.prompt +18 -0
- crossai_cli-0.1.0/cross_ai/cross_stones/domains/healthcare_medical.prompt +18 -0
- crossai_cli-0.1.0/cross_ai/cross_stones/domains/marketing_content.prompt +72 -0
- crossai_cli-0.1.0/cross_ai/cross_stones/domains/research_qa.prompt +18 -0
- crossai_cli-0.1.0/cross_ai/cross_stones/domains/software_development.prompt +19 -0
- crossai_cli-0.1.0/cross_ai/cross_stones/domains/writing_editing.prompt +18 -0
- crossai_cli-0.1.0/cross_ai/discourse.py +192 -0
- crossai_cli-0.1.0/cross_ai/mmd_branding.py +42 -0
- crossai_cli-0.1.0/cross_ai/mmd_data_analysis.py +382 -0
- crossai_cli-0.1.0/cross_ai/mmd_for_speaking.py +225 -0
- crossai_cli-0.1.0/cross_ai/mmd_plot.py +121 -0
- crossai_cli-0.1.0/cross_ai/mmd_process_report.py +285 -0
- crossai_cli-0.1.0/cross_ai/mmd_single_key.py +188 -0
- crossai_cli-0.1.0/cross_ai/mmd_startup.py +69 -0
- crossai_cli-0.1.0/cross_ai/mmd_util.py +234 -0
- crossai_cli-0.1.0/cross_ai/mmd_voice.py +163 -0
- crossai_cli-0.1.0/cross_ai/mmd_web_server.py +88 -0
- crossai_cli-0.1.0/cross_ai/st-admin.py +791 -0
- crossai_cli-0.1.0/cross_ai/st-analyze.py +441 -0
- crossai_cli-0.1.0/cross_ai/st-bang.py +554 -0
- crossai_cli-0.1.0/cross_ai/st-cat.py +122 -0
- crossai_cli-0.1.0/cross_ai/st-cross.py +749 -0
- crossai_cli-0.1.0/cross_ai/st-domain.py +466 -0
- crossai_cli-0.1.0/cross_ai/st-edit.py +368 -0
- crossai_cli-0.1.0/cross_ai/st-fact.py +657 -0
- crossai_cli-0.1.0/cross_ai/st-fetch.py +359 -0
- crossai_cli-0.1.0/cross_ai/st-find.py +375 -0
- crossai_cli-0.1.0/cross_ai/st-fix.py +1926 -0
- crossai_cli-0.1.0/cross_ai/st-gen.py +230 -0
- crossai_cli-0.1.0/cross_ai/st-heatmap.py +394 -0
- crossai_cli-0.1.0/cross_ai/st-ls.py +270 -0
- crossai_cli-0.1.0/cross_ai/st-man.py +247 -0
- crossai_cli-0.1.0/cross_ai/st-merge.py +841 -0
- crossai_cli-0.1.0/cross_ai/st-new.py +169 -0
- crossai_cli-0.1.0/cross_ai/st-plot.py +471 -0
- crossai_cli-0.1.0/cross_ai/st-post.py +334 -0
- crossai_cli-0.1.0/cross_ai/st-prep.py +242 -0
- crossai_cli-0.1.0/cross_ai/st-print.py +497 -0
- crossai_cli-0.1.0/cross_ai/st-read.py +155 -0
- crossai_cli-0.1.0/cross_ai/st-rm.py +176 -0
- crossai_cli-0.1.0/cross_ai/st-speak.py +128 -0
- crossai_cli-0.1.0/cross_ai/st-speed.py +945 -0
- crossai_cli-0.1.0/cross_ai/st-stones.py +1435 -0
- crossai_cli-0.1.0/cross_ai/st-verdict.py +538 -0
- crossai_cli-0.1.0/cross_ai/st-voice.py +237 -0
- crossai_cli-0.1.0/cross_ai/st.py +503 -0
- crossai_cli-0.1.0/cross_ai/template/default.prompt +10 -0
- crossai_cli-0.1.0/crossai_cli.egg-info/PKG-INFO +327 -0
- crossai_cli-0.1.0/crossai_cli.egg-info/SOURCES.txt +80 -0
- crossai_cli-0.1.0/crossai_cli.egg-info/dependency_links.txt +1 -0
- crossai_cli-0.1.0/crossai_cli.egg-info/entry_points.txt +30 -0
- crossai_cli-0.1.0/crossai_cli.egg-info/requires.txt +25 -0
- crossai_cli-0.1.0/crossai_cli.egg-info/top_level.txt +1 -0
- crossai_cli-0.1.0/pyproject.toml +139 -0
- crossai_cli-0.1.0/setup.cfg +4 -0
- crossai_cli-0.1.0/tests/test_cache_timing_preservation.py +256 -0
- crossai_cli-0.1.0/tests/test_cli_help.py +158 -0
- crossai_cli-0.1.0/tests/test_container_loading.py +90 -0
- crossai_cli-0.1.0/tests/test_dotenv_resolution.py +217 -0
- crossai_cli-0.1.0/tests/test_imports.py +106 -0
- crossai_cli-0.1.0/tests/test_mmd_process_report.py +205 -0
- crossai_cli-0.1.0/tests/test_st_admin.py +535 -0
- crossai_cli-0.1.0/tests/test_st_bang.py +158 -0
- crossai_cli-0.1.0/tests/test_st_plot.py +242 -0
- crossai_cli-0.1.0/tests/test_st_speed.py +1075 -0
- crossai_cli-0.1.0/tests/test_st_stones.py +1625 -0
- crossai_cli-0.1.0/tests/test_st_verdict.py +132 -0
- crossai_cli-0.1.0/tests/test_tts_stack.py +62 -0
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
SPDX-License-Identifier: MIT
|
|
2
|
+
|
|
3
|
+
NOTE: Commercial use by organizations is subject to a separate commercial
|
|
4
|
+
license agreement. See COMMERCIAL_LICENSE.md for details.
|
|
5
|
+
|
|
6
|
+
MIT License
|
|
7
|
+
|
|
8
|
+
Copyright (c) 2026 Matt Kraus, Maker Matt Design, Cross (crossai.dev)
|
|
9
|
+
|
|
10
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
11
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
12
|
+
in the Software without restriction, including without limitation the rights
|
|
13
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
14
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
15
|
+
furnished to do so, subject to the following conditions:
|
|
16
|
+
|
|
17
|
+
The above copyright notice and this permission notice shall be included in all
|
|
18
|
+
copies or substantial portions of the Software.
|
|
19
|
+
|
|
20
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
21
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
22
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
23
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
24
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
25
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
26
|
+
SOFTWARE.
|
|
@@ -0,0 +1,327 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: crossai-cli
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: AI reports. Cross-examined. Research reports from multiple AI providers, fact-checked against each other.
|
|
5
|
+
Author: b202i
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://crossai.dev
|
|
8
|
+
Project-URL: Repository, https://github.com/b202i/cross
|
|
9
|
+
Project-URL: Bug Tracker, https://github.com/b202i/cross/issues
|
|
10
|
+
Project-URL: Documentation, https://crossai.dev
|
|
11
|
+
Keywords: ai,llm,fact-check,research,cross-check,benchmark
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Intended Audience :: Science/Research
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
22
|
+
Classifier: Topic :: Text Processing
|
|
23
|
+
Requires-Python: >=3.10
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
License-File: LICENSE
|
|
26
|
+
Requires-Dist: cross-ai-core[all]>=0.4.1
|
|
27
|
+
Requires-Dist: pydiscourse>=1.7.0
|
|
28
|
+
Requires-Dist: requests>=2.32.4
|
|
29
|
+
Requires-Dist: matplotlib>=3.10.1
|
|
30
|
+
Requires-Dist: numpy>=2.2.4
|
|
31
|
+
Requires-Dist: pandas>=2.2.3
|
|
32
|
+
Requires-Dist: pillow>=12.1.1
|
|
33
|
+
Requires-Dist: scipy>=1.15.2
|
|
34
|
+
Requires-Dist: seaborn>=0.13.2
|
|
35
|
+
Requires-Dist: markdown>=3.7
|
|
36
|
+
Requires-Dist: tabulate>=0.9.0
|
|
37
|
+
Requires-Dist: textstat>=0.7.13
|
|
38
|
+
Requires-Dist: tqdm>=4.67.1
|
|
39
|
+
Requires-Dist: weasyprint>=68.0
|
|
40
|
+
Requires-Dist: python-dotenv>=1.1.0
|
|
41
|
+
Requires-Dist: setuptools>=78.1.1
|
|
42
|
+
Requires-Dist: urllib3>=2.6.3
|
|
43
|
+
Provides-Extra: tts
|
|
44
|
+
Requires-Dist: cmudict>=1.0.32; extra == "tts"
|
|
45
|
+
Requires-Dist: pyphen>=0.17.2; extra == "tts"
|
|
46
|
+
Requires-Dist: soundfile>=0.13.1; extra == "tts"
|
|
47
|
+
Requires-Dist: websockets>=15.0.1; extra == "tts"
|
|
48
|
+
Requires-Dist: wyoming>=1.8.0; extra == "tts"
|
|
49
|
+
Requires-Dist: yakyak>=1.7.0; extra == "tts"
|
|
50
|
+
Dynamic: license-file
|
|
51
|
+
|
|
52
|
+
# Cross
|
|
53
|
+
|
|
54
|
+
*AI reports. Cross-examined.*
|
|
55
|
+
|
|
56
|
+
[](LICENSE)
|
|
57
|
+
|
|
58
|
+
> 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.
|
|
59
|
+
|
|
60
|
+
Cross is an open-source command-line tool that generates research reports using
|
|
61
|
+
five AI (more or less) simultaneously, then cross-checks each report against all the others.
|
|
62
|
+
The result is a cross-product fact-check matrix — every AI evaluating every other AI —
|
|
63
|
+
so you can see exactly where they agree, where they diverge, and which claims don't
|
|
64
|
+
hold up. Reports publish directly to Discourse. It's research-grade, keyboard-first,
|
|
65
|
+
and built for people who want to publish accurate content fast.
|
|
66
|
+
|
|
67
|
+
> Cross-check before you publish.
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## Features
|
|
72
|
+
|
|
73
|
+
- **Multi-AI generation** — submit the same prompt to multiple AI providers simultaneously
|
|
74
|
+
- **Cross-product fact-checking** — each AI fact-checks every other AI's report (5×5 matrix)
|
|
75
|
+
- **Analysis and plots** — reading metrics, score heatmaps, bar charts
|
|
76
|
+
- **Discourse publishing** — post stories, fact-checks, and audio to any Discourse site
|
|
77
|
+
- **Text-to-speech** — generate and post MP3 audio via a local TTS server
|
|
78
|
+
- **API response cache** — avoid redundant API calls; replay results instantly
|
|
79
|
+
- **Interactive CLI** — menu-driven `st` command or direct `st-*` commands
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## AI Providers
|
|
84
|
+
|
|
85
|
+
| Provider | Model |
|
|
86
|
+
|---|---|
|
|
87
|
+
| Anthropic | claude-opus-4-5 |
|
|
88
|
+
| xAI | grok-4-latest |
|
|
89
|
+
| OpenAI | gpt-4o |
|
|
90
|
+
| Perplexity | sonar-pro |
|
|
91
|
+
| Google | gemini-2.5-flash |
|
|
92
|
+
|
|
93
|
+
---
|
|
94
|
+
|
|
95
|
+
## Quick Start — Users
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
### 1. Install Homebrew (macOS — skip if already installed)
|
|
99
|
+
|
|
100
|
+
Homebrew is the standard macOS package manager. If you don't have it:
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
### 2. Install pipx
|
|
107
|
+
|
|
108
|
+
`pipx` installs Python CLI tools into isolated environments and puts them on your PATH —
|
|
109
|
+
no virtualenv management, no version conflicts.
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
# macOS
|
|
113
|
+
brew install pipx && pipx ensurepath
|
|
114
|
+
|
|
115
|
+
# Linux — Debian / Ubuntu
|
|
116
|
+
sudo apt install pipx && pipx ensurepath
|
|
117
|
+
|
|
118
|
+
# Linux — Fedora / RHEL
|
|
119
|
+
sudo dnf install pipx && pipx ensurepath
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Restart your terminal after `pipx ensurepath` so the new PATH takes effect.
|
|
123
|
+
|
|
124
|
+
### 3. Install Cross
|
|
125
|
+
|
|
126
|
+
```bash
|
|
127
|
+
pipx install crossai-cli # no TTS audio
|
|
128
|
+
pipx install "crossai-cli[tts]" # with text-to-speech (st-speak, st-voice)
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Both work on Python 3.10–3.13. No version juggling required.
|
|
132
|
+
See [README-TTS-audio.md](README-TTS-audio.md) if you want MP3 audio output.
|
|
133
|
+
|
|
134
|
+
### 4. Set up API keys
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
st-admin --setup
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
The wizard prompts for each API key and saves them to `~/.crossenv`.
|
|
141
|
+
At minimum you need one provider. [Google Gemini](https://aistudio.google.com/app/apikey)
|
|
142
|
+
is free with no credit card required — a good place to start.
|
|
143
|
+
|
|
144
|
+
### 5. Write your first report
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
st-new my_topic.prompt # create a prompt from the template, opens in editor
|
|
148
|
+
st-new --bang my_topic.prompt # generate with all AI, then open the interactive menu
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
---
|
|
152
|
+
|
|
153
|
+
## Quick Start — Developers
|
|
154
|
+
|
|
155
|
+
Developers work from a cloned repo with an editable install. Two repos are needed:
|
|
156
|
+
the main `cross` repo and a separate `cross-story` repo for story containers.
|
|
157
|
+
|
|
158
|
+
### 1. Install Homebrew (macOS — skip if already installed)
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
### 2. Install prerequisites
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
# macOS
|
|
168
|
+
brew install python@3.11 ffmpeg aspell grip
|
|
169
|
+
|
|
170
|
+
# Linux — Debian / Ubuntu
|
|
171
|
+
sudo apt install python3.11 python3.11-venv ffmpeg aspell
|
|
172
|
+
pip install grip
|
|
173
|
+
|
|
174
|
+
# Linux — Fedora / RHEL
|
|
175
|
+
sudo dnf install python3.11 ffmpeg aspell
|
|
176
|
+
pip install grip
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
> **Why Python 3.11?** Cross runs on Python 3.10, 3.11, 3.12, and 3.13 — all four
|
|
180
|
+
> pass the full import test (`tests/test_tts_stack.py`). Python 3.11 is the recommended
|
|
181
|
+
> dev baseline because `requirements.txt` was built and pinned on 3.11. Using 3.12 or
|
|
182
|
+
> 3.13 works fine; 3.11 is just the known-good reference for debugging package conflicts.
|
|
183
|
+
|
|
184
|
+
> **Platform support:** macOS and Linux are fully supported.
|
|
185
|
+
> Windows requires WSL2 — see [README_FAQ.md](README_FAQ.md).
|
|
186
|
+
|
|
187
|
+
### 3. Clone both repos
|
|
188
|
+
|
|
189
|
+
```bash
|
|
190
|
+
git clone https://github.com/b202i/cross.git
|
|
191
|
+
git clone https://github.com/b202i/cross-story.git
|
|
192
|
+
ln -s ~/github/cross-story ~/github/cross/story
|
|
193
|
+
cd cross
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
### 4. Create the virtual environment and install
|
|
197
|
+
|
|
198
|
+
```bash
|
|
199
|
+
python3.11 -m venv .venv
|
|
200
|
+
source .venv/bin/activate
|
|
201
|
+
pip install -r requirements.txt
|
|
202
|
+
pip install -e .
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
### 5. Configure API keys
|
|
206
|
+
|
|
207
|
+
```bash
|
|
208
|
+
cp .env.example .env
|
|
209
|
+
# open .env and fill in at least one API key
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
See [README_opensource.md](README_opensource.md) for provider sign-up links and Discourse
|
|
213
|
+
configuration. API keys live in `.env` — never commit this file.
|
|
214
|
+
|
|
215
|
+
### 6. Generate your first report
|
|
216
|
+
|
|
217
|
+
```bash
|
|
218
|
+
st-new my_topic.prompt # create a prompt from the template, opens in editor
|
|
219
|
+
st-new --bang my_topic.prompt # generate with all AI, then open the interactive menu
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
---
|
|
223
|
+
|
|
224
|
+
## Typical Workflow
|
|
225
|
+
|
|
226
|
+
```
|
|
227
|
+
Generate → View → Edit → Analyze → Post
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
1. **`st-new`** — create a prompt from a template
|
|
231
|
+
2. **`st-bang`** — generate reports from all 5 AI in parallel
|
|
232
|
+
3. **`st-prep`** — extract title, text, markdown, and spoken versions
|
|
233
|
+
4. **`st-fact`** / **`st-cross`** — fact-check one story or the full 5×5 matrix
|
|
234
|
+
5. **`st-analyze`** — generate a cross-product summary report
|
|
235
|
+
6. **`st-edit`** — review and refine in vim with optional browser preview
|
|
236
|
+
7. **`st-post`** — publish to Discourse with optional MP3 audio
|
|
237
|
+
|
|
238
|
+
All steps are also accessible through the `st` interactive menu.
|
|
239
|
+
|
|
240
|
+
---
|
|
241
|
+
|
|
242
|
+
## Command Reference
|
|
243
|
+
|
|
244
|
+
| Command | Purpose |
|
|
245
|
+
|---|---|
|
|
246
|
+
| `st` | Interactive menu — accepts `.json` or `.prompt`; generates `.json` if needed |
|
|
247
|
+
| `st-new` | Create a prompt from template; optionally generate with `--bang` or `--st` |
|
|
248
|
+
| `st-gen` | Generate a story from a prompt with one AI |
|
|
249
|
+
| `st-bang` | Generate stories from all AI in parallel |
|
|
250
|
+
| `st-prep` | Process raw AI output into title / markdown / text / spoken |
|
|
251
|
+
| `st-merge` | Merge multiple AI stories into one |
|
|
252
|
+
| `st-edit` | Edit or browser-preview a story |
|
|
253
|
+
| `st-ls` | List stories and fact-checks in a container |
|
|
254
|
+
| `st-find` | Search for keywords (with wildcards and boolean operators) in titles, prompts, and stories |
|
|
255
|
+
| `st-fact` | Fact-check a story with one AI |
|
|
256
|
+
| `st-cross` | Cross-product fact-check — all stories × all AI |
|
|
257
|
+
| `st-analyze` | Generate a cross-product analysis report |
|
|
258
|
+
| `st-speed` | Analyze AI performance and speed from timing data |
|
|
259
|
+
| `st-fix` | Revise a story using its fact-check results |
|
|
260
|
+
| `st-read` | Show reading-level metrics |
|
|
261
|
+
| `st-plot` | Plot cross-product scores |
|
|
262
|
+
| `st-heatmap` | Score heatmap across AI combinations |
|
|
263
|
+
| `st-post` | Post story (and optional audio) to Discourse |
|
|
264
|
+
| `st-speak` | Generate TTS audio for a story |
|
|
265
|
+
| `st-voice` | Manage TTS voice selection |
|
|
266
|
+
| `st-rm` | Remove a story or fact-check from a container |
|
|
267
|
+
| `st-cat` | Print raw JSON container contents |
|
|
268
|
+
|
|
269
|
+
---
|
|
270
|
+
|
|
271
|
+
## Project Structure
|
|
272
|
+
|
|
273
|
+
```
|
|
274
|
+
cross/
|
|
275
|
+
├── cross_ai/ # Python package — all runtime code lives here
|
|
276
|
+
│ ├── st.py # Interactive menu (command builder)
|
|
277
|
+
│ ├── st-*.py # Individual CLI commands (28 tools)
|
|
278
|
+
│ ├── ai_handler.py # AI dispatcher (shim → cross-ai-core)
|
|
279
|
+
│ ├── base_handler.py # Abstract base class shim → cross-ai-core
|
|
280
|
+
│ ├── discourse.py # Discourse API client
|
|
281
|
+
│ ├── mmd_*.py # Support modules (processing, plotting, voice, util)
|
|
282
|
+
│ ├── commands.py # Entry-point dispatch for pyproject.toml
|
|
283
|
+
│ └── template/ # Prompt templates for st-new
|
|
284
|
+
├── tests/ # Test suite
|
|
285
|
+
├── docs/wiki/ # GitHub Wiki source (auto-built)
|
|
286
|
+
├── pyproject.toml # Package metadata and entry points
|
|
287
|
+
├── requirements.txt # Pinned Python dependencies
|
|
288
|
+
├── .env # API keys and Discourse credentials (never commit)
|
|
289
|
+
└── tmp/ # Transient coordination files (gitignored)
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
---
|
|
293
|
+
|
|
294
|
+
## Further Reading
|
|
295
|
+
|
|
296
|
+
| File | Contents |
|
|
297
|
+
|---|---|
|
|
298
|
+
| [README_install.md](README_install.md) | Full install guide for a new machine (clone, venv, symlinks, keys) |
|
|
299
|
+
| [README-TTS-audio.md](README-TTS-audio.md) | TTS audio setup — Python versions, platform install, Piper server, voices |
|
|
300
|
+
| [README_post.md](README_post.md) | Publishing guide — Discourse, GitHub Gist, Bluesky, Reddit, X.com |
|
|
301
|
+
| [README_ui.md](README_ui.md) | Full menu reference and UI conventions |
|
|
302
|
+
| [README_FAQ.md](README_FAQ.md) | Frequently asked questions |
|
|
303
|
+
| [ERROR_QUICK_REFERENCE.md](ERROR_QUICK_REFERENCE.md) | API errors and solutions — quota limits, rate limits, troubleshooting |
|
|
304
|
+
| [README_opensource.md](README_opensource.md) | Setup, API keys, Discourse configuration |
|
|
305
|
+
| [README_devel.md](README_devel.md) | Developer notes and architecture |
|
|
306
|
+
| [README_cross_product.md](README_cross_product.md) | Cross-product analysis deep dive |
|
|
307
|
+
| [README_speed_comparison.md](README_speed_comparison.md) | AI performance metrics and speed comparison strategy |
|
|
308
|
+
| [README_testing.md](README_testing.md) | Regression testing strategy and best practices |
|
|
309
|
+
| [TESTING_QUICKSTART.md](TESTING_QUICKSTART.md) | Run tests quickly — commands and current status |
|
|
310
|
+
|
|
311
|
+
---
|
|
312
|
+
|
|
313
|
+
## License
|
|
314
|
+
|
|
315
|
+
MIT — free for personal, academic, and open-source use.
|
|
316
|
+
See [LICENSE](LICENSE) for the full text.
|
|
317
|
+
|
|
318
|
+
Organizations deploying Cross in commercial or government contexts are encouraged
|
|
319
|
+
to reach out for a licensing and support agreement. See [COMMERCIAL_LICENSE.md](COMMERCIAL_LICENSE.md).
|
|
320
|
+
|
|
321
|
+
For the full licensing strategy and roadmap see [README_license.md](README_license.md).
|
|
322
|
+
|
|
323
|
+
---
|
|
324
|
+
|
|
325
|
+
*AI reports. Cross-examined.*
|
|
326
|
+
*GitHub: [github.com/b202i/cross](https://github.com/b202i/cross)*
|
|
327
|
+
|
|
@@ -0,0 +1,276 @@
|
|
|
1
|
+
# Cross
|
|
2
|
+
|
|
3
|
+
*AI reports. Cross-examined.*
|
|
4
|
+
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
|
|
7
|
+
> 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.
|
|
8
|
+
|
|
9
|
+
Cross is an open-source command-line tool that generates research reports using
|
|
10
|
+
five AI (more or less) simultaneously, then cross-checks each report against all the others.
|
|
11
|
+
The result is a cross-product fact-check matrix — every AI evaluating every other AI —
|
|
12
|
+
so you can see exactly where they agree, where they diverge, and which claims don't
|
|
13
|
+
hold up. Reports publish directly to Discourse. It's research-grade, keyboard-first,
|
|
14
|
+
and built for people who want to publish accurate content fast.
|
|
15
|
+
|
|
16
|
+
> Cross-check before you publish.
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## Features
|
|
21
|
+
|
|
22
|
+
- **Multi-AI generation** — submit the same prompt to multiple AI providers simultaneously
|
|
23
|
+
- **Cross-product fact-checking** — each AI fact-checks every other AI's report (5×5 matrix)
|
|
24
|
+
- **Analysis and plots** — reading metrics, score heatmaps, bar charts
|
|
25
|
+
- **Discourse publishing** — post stories, fact-checks, and audio to any Discourse site
|
|
26
|
+
- **Text-to-speech** — generate and post MP3 audio via a local TTS server
|
|
27
|
+
- **API response cache** — avoid redundant API calls; replay results instantly
|
|
28
|
+
- **Interactive CLI** — menu-driven `st` command or direct `st-*` commands
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## AI Providers
|
|
33
|
+
|
|
34
|
+
| Provider | Model |
|
|
35
|
+
|---|---|
|
|
36
|
+
| Anthropic | claude-opus-4-5 |
|
|
37
|
+
| xAI | grok-4-latest |
|
|
38
|
+
| OpenAI | gpt-4o |
|
|
39
|
+
| Perplexity | sonar-pro |
|
|
40
|
+
| Google | gemini-2.5-flash |
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## Quick Start — Users
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
### 1. Install Homebrew (macOS — skip if already installed)
|
|
48
|
+
|
|
49
|
+
Homebrew is the standard macOS package manager. If you don't have it:
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
### 2. Install pipx
|
|
56
|
+
|
|
57
|
+
`pipx` installs Python CLI tools into isolated environments and puts them on your PATH —
|
|
58
|
+
no virtualenv management, no version conflicts.
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
# macOS
|
|
62
|
+
brew install pipx && pipx ensurepath
|
|
63
|
+
|
|
64
|
+
# Linux — Debian / Ubuntu
|
|
65
|
+
sudo apt install pipx && pipx ensurepath
|
|
66
|
+
|
|
67
|
+
# Linux — Fedora / RHEL
|
|
68
|
+
sudo dnf install pipx && pipx ensurepath
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Restart your terminal after `pipx ensurepath` so the new PATH takes effect.
|
|
72
|
+
|
|
73
|
+
### 3. Install Cross
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
pipx install crossai-cli # no TTS audio
|
|
77
|
+
pipx install "crossai-cli[tts]" # with text-to-speech (st-speak, st-voice)
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Both work on Python 3.10–3.13. No version juggling required.
|
|
81
|
+
See [README-TTS-audio.md](README-TTS-audio.md) if you want MP3 audio output.
|
|
82
|
+
|
|
83
|
+
### 4. Set up API keys
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
st-admin --setup
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
The wizard prompts for each API key and saves them to `~/.crossenv`.
|
|
90
|
+
At minimum you need one provider. [Google Gemini](https://aistudio.google.com/app/apikey)
|
|
91
|
+
is free with no credit card required — a good place to start.
|
|
92
|
+
|
|
93
|
+
### 5. Write your first report
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
st-new my_topic.prompt # create a prompt from the template, opens in editor
|
|
97
|
+
st-new --bang my_topic.prompt # generate with all AI, then open the interactive menu
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
## Quick Start — Developers
|
|
103
|
+
|
|
104
|
+
Developers work from a cloned repo with an editable install. Two repos are needed:
|
|
105
|
+
the main `cross` repo and a separate `cross-story` repo for story containers.
|
|
106
|
+
|
|
107
|
+
### 1. Install Homebrew (macOS — skip if already installed)
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### 2. Install prerequisites
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
# macOS
|
|
117
|
+
brew install python@3.11 ffmpeg aspell grip
|
|
118
|
+
|
|
119
|
+
# Linux — Debian / Ubuntu
|
|
120
|
+
sudo apt install python3.11 python3.11-venv ffmpeg aspell
|
|
121
|
+
pip install grip
|
|
122
|
+
|
|
123
|
+
# Linux — Fedora / RHEL
|
|
124
|
+
sudo dnf install python3.11 ffmpeg aspell
|
|
125
|
+
pip install grip
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
> **Why Python 3.11?** Cross runs on Python 3.10, 3.11, 3.12, and 3.13 — all four
|
|
129
|
+
> pass the full import test (`tests/test_tts_stack.py`). Python 3.11 is the recommended
|
|
130
|
+
> dev baseline because `requirements.txt` was built and pinned on 3.11. Using 3.12 or
|
|
131
|
+
> 3.13 works fine; 3.11 is just the known-good reference for debugging package conflicts.
|
|
132
|
+
|
|
133
|
+
> **Platform support:** macOS and Linux are fully supported.
|
|
134
|
+
> Windows requires WSL2 — see [README_FAQ.md](README_FAQ.md).
|
|
135
|
+
|
|
136
|
+
### 3. Clone both repos
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
git clone https://github.com/b202i/cross.git
|
|
140
|
+
git clone https://github.com/b202i/cross-story.git
|
|
141
|
+
ln -s ~/github/cross-story ~/github/cross/story
|
|
142
|
+
cd cross
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
### 4. Create the virtual environment and install
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
python3.11 -m venv .venv
|
|
149
|
+
source .venv/bin/activate
|
|
150
|
+
pip install -r requirements.txt
|
|
151
|
+
pip install -e .
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
### 5. Configure API keys
|
|
155
|
+
|
|
156
|
+
```bash
|
|
157
|
+
cp .env.example .env
|
|
158
|
+
# open .env and fill in at least one API key
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
See [README_opensource.md](README_opensource.md) for provider sign-up links and Discourse
|
|
162
|
+
configuration. API keys live in `.env` — never commit this file.
|
|
163
|
+
|
|
164
|
+
### 6. Generate your first report
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
st-new my_topic.prompt # create a prompt from the template, opens in editor
|
|
168
|
+
st-new --bang my_topic.prompt # generate with all AI, then open the interactive menu
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
---
|
|
172
|
+
|
|
173
|
+
## Typical Workflow
|
|
174
|
+
|
|
175
|
+
```
|
|
176
|
+
Generate → View → Edit → Analyze → Post
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
1. **`st-new`** — create a prompt from a template
|
|
180
|
+
2. **`st-bang`** — generate reports from all 5 AI in parallel
|
|
181
|
+
3. **`st-prep`** — extract title, text, markdown, and spoken versions
|
|
182
|
+
4. **`st-fact`** / **`st-cross`** — fact-check one story or the full 5×5 matrix
|
|
183
|
+
5. **`st-analyze`** — generate a cross-product summary report
|
|
184
|
+
6. **`st-edit`** — review and refine in vim with optional browser preview
|
|
185
|
+
7. **`st-post`** — publish to Discourse with optional MP3 audio
|
|
186
|
+
|
|
187
|
+
All steps are also accessible through the `st` interactive menu.
|
|
188
|
+
|
|
189
|
+
---
|
|
190
|
+
|
|
191
|
+
## Command Reference
|
|
192
|
+
|
|
193
|
+
| Command | Purpose |
|
|
194
|
+
|---|---|
|
|
195
|
+
| `st` | Interactive menu — accepts `.json` or `.prompt`; generates `.json` if needed |
|
|
196
|
+
| `st-new` | Create a prompt from template; optionally generate with `--bang` or `--st` |
|
|
197
|
+
| `st-gen` | Generate a story from a prompt with one AI |
|
|
198
|
+
| `st-bang` | Generate stories from all AI in parallel |
|
|
199
|
+
| `st-prep` | Process raw AI output into title / markdown / text / spoken |
|
|
200
|
+
| `st-merge` | Merge multiple AI stories into one |
|
|
201
|
+
| `st-edit` | Edit or browser-preview a story |
|
|
202
|
+
| `st-ls` | List stories and fact-checks in a container |
|
|
203
|
+
| `st-find` | Search for keywords (with wildcards and boolean operators) in titles, prompts, and stories |
|
|
204
|
+
| `st-fact` | Fact-check a story with one AI |
|
|
205
|
+
| `st-cross` | Cross-product fact-check — all stories × all AI |
|
|
206
|
+
| `st-analyze` | Generate a cross-product analysis report |
|
|
207
|
+
| `st-speed` | Analyze AI performance and speed from timing data |
|
|
208
|
+
| `st-fix` | Revise a story using its fact-check results |
|
|
209
|
+
| `st-read` | Show reading-level metrics |
|
|
210
|
+
| `st-plot` | Plot cross-product scores |
|
|
211
|
+
| `st-heatmap` | Score heatmap across AI combinations |
|
|
212
|
+
| `st-post` | Post story (and optional audio) to Discourse |
|
|
213
|
+
| `st-speak` | Generate TTS audio for a story |
|
|
214
|
+
| `st-voice` | Manage TTS voice selection |
|
|
215
|
+
| `st-rm` | Remove a story or fact-check from a container |
|
|
216
|
+
| `st-cat` | Print raw JSON container contents |
|
|
217
|
+
|
|
218
|
+
---
|
|
219
|
+
|
|
220
|
+
## Project Structure
|
|
221
|
+
|
|
222
|
+
```
|
|
223
|
+
cross/
|
|
224
|
+
├── cross_ai/ # Python package — all runtime code lives here
|
|
225
|
+
│ ├── st.py # Interactive menu (command builder)
|
|
226
|
+
│ ├── st-*.py # Individual CLI commands (28 tools)
|
|
227
|
+
│ ├── ai_handler.py # AI dispatcher (shim → cross-ai-core)
|
|
228
|
+
│ ├── base_handler.py # Abstract base class shim → cross-ai-core
|
|
229
|
+
│ ├── discourse.py # Discourse API client
|
|
230
|
+
│ ├── mmd_*.py # Support modules (processing, plotting, voice, util)
|
|
231
|
+
│ ├── commands.py # Entry-point dispatch for pyproject.toml
|
|
232
|
+
│ └── template/ # Prompt templates for st-new
|
|
233
|
+
├── tests/ # Test suite
|
|
234
|
+
├── docs/wiki/ # GitHub Wiki source (auto-built)
|
|
235
|
+
├── pyproject.toml # Package metadata and entry points
|
|
236
|
+
├── requirements.txt # Pinned Python dependencies
|
|
237
|
+
├── .env # API keys and Discourse credentials (never commit)
|
|
238
|
+
└── tmp/ # Transient coordination files (gitignored)
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
---
|
|
242
|
+
|
|
243
|
+
## Further Reading
|
|
244
|
+
|
|
245
|
+
| File | Contents |
|
|
246
|
+
|---|---|
|
|
247
|
+
| [README_install.md](README_install.md) | Full install guide for a new machine (clone, venv, symlinks, keys) |
|
|
248
|
+
| [README-TTS-audio.md](README-TTS-audio.md) | TTS audio setup — Python versions, platform install, Piper server, voices |
|
|
249
|
+
| [README_post.md](README_post.md) | Publishing guide — Discourse, GitHub Gist, Bluesky, Reddit, X.com |
|
|
250
|
+
| [README_ui.md](README_ui.md) | Full menu reference and UI conventions |
|
|
251
|
+
| [README_FAQ.md](README_FAQ.md) | Frequently asked questions |
|
|
252
|
+
| [ERROR_QUICK_REFERENCE.md](ERROR_QUICK_REFERENCE.md) | API errors and solutions — quota limits, rate limits, troubleshooting |
|
|
253
|
+
| [README_opensource.md](README_opensource.md) | Setup, API keys, Discourse configuration |
|
|
254
|
+
| [README_devel.md](README_devel.md) | Developer notes and architecture |
|
|
255
|
+
| [README_cross_product.md](README_cross_product.md) | Cross-product analysis deep dive |
|
|
256
|
+
| [README_speed_comparison.md](README_speed_comparison.md) | AI performance metrics and speed comparison strategy |
|
|
257
|
+
| [README_testing.md](README_testing.md) | Regression testing strategy and best practices |
|
|
258
|
+
| [TESTING_QUICKSTART.md](TESTING_QUICKSTART.md) | Run tests quickly — commands and current status |
|
|
259
|
+
|
|
260
|
+
---
|
|
261
|
+
|
|
262
|
+
## License
|
|
263
|
+
|
|
264
|
+
MIT — free for personal, academic, and open-source use.
|
|
265
|
+
See [LICENSE](LICENSE) for the full text.
|
|
266
|
+
|
|
267
|
+
Organizations deploying Cross in commercial or government contexts are encouraged
|
|
268
|
+
to reach out for a licensing and support agreement. See [COMMERCIAL_LICENSE.md](COMMERCIAL_LICENSE.md).
|
|
269
|
+
|
|
270
|
+
For the full licensing strategy and roadmap see [README_license.md](README_license.md).
|
|
271
|
+
|
|
272
|
+
---
|
|
273
|
+
|
|
274
|
+
*AI reports. Cross-examined.*
|
|
275
|
+
*GitHub: [github.com/b202i/cross](https://github.com/b202i/cross)*
|
|
276
|
+
|
|
File without changes
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# ai_error_handler.py — compatibility shim
|
|
2
|
+
# Source of truth: cross-ai-core package (cross_ai_core.ai_error_handler)
|
|
3
|
+
from cross_ai_core.ai_error_handler import * # noqa: F401, F403
|
|
4
|
+
from cross_ai_core.ai_error_handler import ( # explicit for IDE / type checkers
|
|
5
|
+
handle_api_error,
|
|
6
|
+
is_quota_error,
|
|
7
|
+
is_rate_limit_error,
|
|
8
|
+
is_transient_error,
|
|
9
|
+
get_error_type,
|
|
10
|
+
retry_with_backoff,
|
|
11
|
+
CrossAIError,
|
|
12
|
+
QuotaExceededError,
|
|
13
|
+
RateLimitError,
|
|
14
|
+
TransientError,
|
|
15
|
+
)
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# ai_handler.py — compatibility shim
|
|
2
|
+
# Source of truth: cross-ai-core package (cross_ai_core.ai_handler)
|
|
3
|
+
# This file exists so st-*.py files and tests can continue to use:
|
|
4
|
+
# from ai_handler import process_prompt, get_content, ...
|
|
5
|
+
from cross_ai_core.ai_handler import * # noqa: F401, F403
|
|
6
|
+
from cross_ai_core.ai_handler import ( # explicit for IDE / type checkers
|
|
7
|
+
AI_HANDLER_REGISTRY,
|
|
8
|
+
AI_LIST,
|
|
9
|
+
AIResponse,
|
|
10
|
+
_API_KEY_ENV_VARS, # private — needed by tests
|
|
11
|
+
check_api_key,
|
|
12
|
+
get_ai_list,
|
|
13
|
+
get_ai_make,
|
|
14
|
+
get_ai_model,
|
|
15
|
+
get_content,
|
|
16
|
+
get_data_content,
|
|
17
|
+
get_data_title,
|
|
18
|
+
get_default_ai,
|
|
19
|
+
get_usage,
|
|
20
|
+
process_prompt,
|
|
21
|
+
put_content,
|
|
22
|
+
)
|