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.
Files changed (82) hide show
  1. crossai_cli-0.1.0/LICENSE +26 -0
  2. crossai_cli-0.1.0/PKG-INFO +327 -0
  3. crossai_cli-0.1.0/README.md +276 -0
  4. crossai_cli-0.1.0/cross_ai/__init__.py +0 -0
  5. crossai_cli-0.1.0/cross_ai/ai_error_handler.py +15 -0
  6. crossai_cli-0.1.0/cross_ai/ai_handler.py +22 -0
  7. crossai_cli-0.1.0/cross_ai/ai_url.py +89 -0
  8. crossai_cli-0.1.0/cross_ai/base_handler.py +3 -0
  9. crossai_cli-0.1.0/cross_ai/commands.py +54 -0
  10. crossai_cli-0.1.0/cross_ai/cross_stones/cross-stones-10.json +57 -0
  11. crossai_cli-0.1.0/cross_ai/cross_stones/domains/creative_media.prompt +18 -0
  12. crossai_cli-0.1.0/cross_ai/cross_stones/domains/customer_service.prompt +12 -0
  13. crossai_cli-0.1.0/cross_ai/cross_stones/domains/data_analytics.prompt +18 -0
  14. crossai_cli-0.1.0/cross_ai/cross_stones/domains/education_learning.prompt +18 -0
  15. crossai_cli-0.1.0/cross_ai/cross_stones/domains/finance_business.prompt +18 -0
  16. crossai_cli-0.1.0/cross_ai/cross_stones/domains/healthcare_medical.prompt +18 -0
  17. crossai_cli-0.1.0/cross_ai/cross_stones/domains/marketing_content.prompt +72 -0
  18. crossai_cli-0.1.0/cross_ai/cross_stones/domains/research_qa.prompt +18 -0
  19. crossai_cli-0.1.0/cross_ai/cross_stones/domains/software_development.prompt +19 -0
  20. crossai_cli-0.1.0/cross_ai/cross_stones/domains/writing_editing.prompt +18 -0
  21. crossai_cli-0.1.0/cross_ai/discourse.py +192 -0
  22. crossai_cli-0.1.0/cross_ai/mmd_branding.py +42 -0
  23. crossai_cli-0.1.0/cross_ai/mmd_data_analysis.py +382 -0
  24. crossai_cli-0.1.0/cross_ai/mmd_for_speaking.py +225 -0
  25. crossai_cli-0.1.0/cross_ai/mmd_plot.py +121 -0
  26. crossai_cli-0.1.0/cross_ai/mmd_process_report.py +285 -0
  27. crossai_cli-0.1.0/cross_ai/mmd_single_key.py +188 -0
  28. crossai_cli-0.1.0/cross_ai/mmd_startup.py +69 -0
  29. crossai_cli-0.1.0/cross_ai/mmd_util.py +234 -0
  30. crossai_cli-0.1.0/cross_ai/mmd_voice.py +163 -0
  31. crossai_cli-0.1.0/cross_ai/mmd_web_server.py +88 -0
  32. crossai_cli-0.1.0/cross_ai/st-admin.py +791 -0
  33. crossai_cli-0.1.0/cross_ai/st-analyze.py +441 -0
  34. crossai_cli-0.1.0/cross_ai/st-bang.py +554 -0
  35. crossai_cli-0.1.0/cross_ai/st-cat.py +122 -0
  36. crossai_cli-0.1.0/cross_ai/st-cross.py +749 -0
  37. crossai_cli-0.1.0/cross_ai/st-domain.py +466 -0
  38. crossai_cli-0.1.0/cross_ai/st-edit.py +368 -0
  39. crossai_cli-0.1.0/cross_ai/st-fact.py +657 -0
  40. crossai_cli-0.1.0/cross_ai/st-fetch.py +359 -0
  41. crossai_cli-0.1.0/cross_ai/st-find.py +375 -0
  42. crossai_cli-0.1.0/cross_ai/st-fix.py +1926 -0
  43. crossai_cli-0.1.0/cross_ai/st-gen.py +230 -0
  44. crossai_cli-0.1.0/cross_ai/st-heatmap.py +394 -0
  45. crossai_cli-0.1.0/cross_ai/st-ls.py +270 -0
  46. crossai_cli-0.1.0/cross_ai/st-man.py +247 -0
  47. crossai_cli-0.1.0/cross_ai/st-merge.py +841 -0
  48. crossai_cli-0.1.0/cross_ai/st-new.py +169 -0
  49. crossai_cli-0.1.0/cross_ai/st-plot.py +471 -0
  50. crossai_cli-0.1.0/cross_ai/st-post.py +334 -0
  51. crossai_cli-0.1.0/cross_ai/st-prep.py +242 -0
  52. crossai_cli-0.1.0/cross_ai/st-print.py +497 -0
  53. crossai_cli-0.1.0/cross_ai/st-read.py +155 -0
  54. crossai_cli-0.1.0/cross_ai/st-rm.py +176 -0
  55. crossai_cli-0.1.0/cross_ai/st-speak.py +128 -0
  56. crossai_cli-0.1.0/cross_ai/st-speed.py +945 -0
  57. crossai_cli-0.1.0/cross_ai/st-stones.py +1435 -0
  58. crossai_cli-0.1.0/cross_ai/st-verdict.py +538 -0
  59. crossai_cli-0.1.0/cross_ai/st-voice.py +237 -0
  60. crossai_cli-0.1.0/cross_ai/st.py +503 -0
  61. crossai_cli-0.1.0/cross_ai/template/default.prompt +10 -0
  62. crossai_cli-0.1.0/crossai_cli.egg-info/PKG-INFO +327 -0
  63. crossai_cli-0.1.0/crossai_cli.egg-info/SOURCES.txt +80 -0
  64. crossai_cli-0.1.0/crossai_cli.egg-info/dependency_links.txt +1 -0
  65. crossai_cli-0.1.0/crossai_cli.egg-info/entry_points.txt +30 -0
  66. crossai_cli-0.1.0/crossai_cli.egg-info/requires.txt +25 -0
  67. crossai_cli-0.1.0/crossai_cli.egg-info/top_level.txt +1 -0
  68. crossai_cli-0.1.0/pyproject.toml +139 -0
  69. crossai_cli-0.1.0/setup.cfg +4 -0
  70. crossai_cli-0.1.0/tests/test_cache_timing_preservation.py +256 -0
  71. crossai_cli-0.1.0/tests/test_cli_help.py +158 -0
  72. crossai_cli-0.1.0/tests/test_container_loading.py +90 -0
  73. crossai_cli-0.1.0/tests/test_dotenv_resolution.py +217 -0
  74. crossai_cli-0.1.0/tests/test_imports.py +106 -0
  75. crossai_cli-0.1.0/tests/test_mmd_process_report.py +205 -0
  76. crossai_cli-0.1.0/tests/test_st_admin.py +535 -0
  77. crossai_cli-0.1.0/tests/test_st_bang.py +158 -0
  78. crossai_cli-0.1.0/tests/test_st_plot.py +242 -0
  79. crossai_cli-0.1.0/tests/test_st_speed.py +1075 -0
  80. crossai_cli-0.1.0/tests/test_st_stones.py +1625 -0
  81. crossai_cli-0.1.0/tests/test_st_verdict.py +132 -0
  82. 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: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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
+ )