docs/CODEX_NOTES.md

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.