| # Codex Notes |
|
|
| ## How Codex helped |
|
|
| Codex reviewed the existing repository, identified the old React/FastAPI/Supabase/Groq architecture, and reshaped the project into a focused Hugging Face Space called **Headline Booster AI**. |
|
|
| ## Repository analysis |
|
|
| The original repository was an English-learning chatbot named COMPARTIR AI. It used a React/Vite frontend, Tailwind custom styling, FastAPI backend routes, Supabase authentication/session storage, external AI-service wiring, and multiple chat components for a broader learning product. |
|
|
| Those pieces did not match the new product goal: a small-model headline optimizer that takes one weak headline and returns a stable structured report. |
|
|
| ## Current architecture |
|
|
| - `index.html` owns the complete frontend: HTML, CSS, JavaScript, local browser history, layout, and rendering. |
| - `app.py` is backend/API only, implemented with `gradio.Server` instead of `gr.Blocks()`. |
| - Browser history is stored in `localStorage`; the backend does not store sessions. |
| - The frontend now uses step-based endpoints: `POST /api/analyze_headline`, `POST /api/create_proposals`, and `POST /api/choose_winner`. The one-shot `POST /api/improve_headline` remains for compatibility. |
|
|
| ## What was reused |
|
|
| - The product-level idea of a left sidebar plus clean main workspace. |
| - A warm, minimal visual direction with large rounded inputs and cards. |
| - The hackathon-oriented tiny-model plan around `Qwen/Qwen2.5-1.5B-Instruct`. |
|
|
| ## What was removed |
|
|
| - The old React/Vite application. |
| - The prior Gradio Blocks visual layer. |
| - FastAPI backend files from the original app. |
| - Supabase authentication and protected routes. |
| - External paid generation APIs. |
| - English-learning services: translation, grammar correction, vocabulary, roadmap, personalities, speech, login, usage counters, and advanced session flows. |
| - Backend chat history logic; history is local to each browser. |
|
|
| ## Files created or refactored |
|
|
| - `app.py`: Gradio Server backend/API with `/`, `/health`, and `POST /api/improve_headline`. |
| - `index.html`: complete custom frontend inspired by the reference image. |
| - `requirements.txt`: Gradio plus optional Tiny Titan runtime dependencies. |
| - `README.md`: rewritten for the optimizer architecture and Hugging Face Spaces metadata. |
| - `docs/CODEX_NOTES.md`: documents repository analysis and migration decisions. |
| - `docs/FIELD_NOTES.md`: documents the product problem, small-model angle, and future work. |
| - `docs/COMMIT_LOG.md`: records relevant Git commits for hackathon/Codex review. |
| - `docs/FRONTEND_REFERENCE_NOTES.md`: explains how the image/reference informed the frontend. |
| - `docs/TINY_TITAN_PLAN.md`: documents the small-model runtime path and fallback behavior. |
|
|
| ## Output contract |
|
|
| The backend splits the experience into a guided conversation. It first returns a compact persuasive X-ray of the headline, then creates three proposals only after user confirmation, then asks for the intended use before selecting a winner. The model is only asked for the proposal-generation part; diagnosis and winner choice are backend-controlled. |
|
|
| ## Current status |
|
|
| Headline Booster AI can run with `python app.py`. Locally, `USE_REAL_MODEL=auto` resolves to mock mode. On Hugging Face Spaces, `USE_REAL_MODEL=auto` resolves to the tiny model path. If model loading or model JSON validation fails, the backend uses the mock fallback so the app does not break. |
|
|
| ## Next steps |
|
|
| - Deploy the repository as a Hugging Face Space. |
| - Test the real `Qwen/Qwen2.5-1.5B-Instruct` path on the Space runtime. |
| - Compare user-facing quality against the fallback mock and tighten the prompt if needed. |
|
|
