diff --git a/README.md b/README.md index 71488c4..6f7378d 100644 --- a/README.md +++ b/README.md @@ -1,52 +1,193 @@ -# Gitlab component template +# ITSulu Blog Publisher - +## Overview - - +ITSulu Blog Publisher replaces fragile external blog-generation workflows with a fully server-side Odoo addon. Generate blog posts on-demand or on a schedule using Claude (Anthropic), OpenAI, Google Gemini, or Ollama. Posts are auto-populated with SEO metadata and social media copy, ready to publish. -## Components +## Features -### `` +- **Multi-LLM Support**: Anthropic Claude, OpenAI GPT, Google Gemini, Ollama / Open WebUI +- **Three Configurable Daily Slots**: morning, afternoon, evening — each with independent LLM provider + model selection +- **On-Demand & Scheduled Generation**: Backend wizard + website toolbar button + hourly cron dispatcher +- **Topic Queue**: Priority-ranked topic suggestions from ITSulu/company services +- **Single Structured-JSON LLM Call**: Lowest possible token usage — one API call returns title, body, SEO fields, tags, and social copy +- **Auto-Populated SEO**: meta title, description, keywords, tags +- **Social Media Copy**: X/Twitter (A+B), BlueSky (A+B), Mastodon, LinkedIn — platform-specific length limits +- **Notification Email**: Matches ITSulu Insights template format with social copy and source citations +- **Generation Log**: Full audit trail with token usage, duration, error messages, and retry button +- **Editable Prompt Templates**: System and user prompts in Settings UI -Use this component to ``. +## Requirements -To add this component to your CI/CD pipeline, add the following include entry to your -project's CI/CD configuration: +### Odoo Version +- **Target**: Odoo 17.0 Community (development branch) +- **Planned**: Odoo 14.0 Community (separate branch for App Store) -```yaml -include: - - component: https://gitlab.com//@ +### Python Dependencies +- `requests` (included in Odoo) +- `anthropic` (for Anthropic Claude) — optional +- `openai` (for OpenAI) — optional +- `google-generativeai` (for Gemini) — optional +- Ollama uses OpenAI-compatible REST API (no SDK needed) + +### Odoo Module Dependencies +- `base` +- `website` +- `website_blog` +- `mail` +- `base_setup` + +## Installation + +### From Source (Development) + +```bash +# Clone the addon +git clone https://github.com/itsulu/itsulu-blog-publisher.git +cd itsulu-blog-publisher + +# Copy addon into your Odoo addons path +cp -r addons/itsulu_blog_publisher /path/to/odoo/addons/ + +# Install via Odoo UI: Apps > Search "Blog Publisher" > Install ``` -Where `` is the release tag you want to use ([releases list](https://gitlab.com//-/releases)). +### Docker (Testing) -## Inputs +```bash +docker build -t itsulu-blog-publisher:latest . +docker run -p 8069:8069 itsulu-blog-publisher:latest +``` -The template contains some optional [inputs](https://docs.gitlab.com/ee/ci/yaml/inputs.html): +## Configuration - +1. **Enable the addon**: Apps > Search "Blog Publisher" > Install +2. **Settings**: Go to Blog Publisher > Settings + - Set API keys for your LLM provider(s) + - Configure default LLM provider and model + - Set notification email recipients + - (Optional) Edit system and user prompt templates +3. **Create a blog**: Website > Blogs (if not already created) +4. **Schedule slots**: Blog Publisher > Schedule Slots + - Create or edit morning/afternoon/evening slots + - Select target blog, LLM provider + model, auto-publish +5. **Activate scheduling**: Set `active=True` on desired slots + enable the cron in Settings -| Input | Default value | Description | -|------------|------------------|-------------| -| `job_name` | `job-template` | The job name. | -| `image` | `busybox:latest` | The container image to use to run the job. | -| `stage` | `test` | The stage name for the job. | +## Usage -## Documentation +### Generate On-Demand +1. **From backend**: Blog Publisher > Generate Now (wizard selects topic, LLM, blog, tone) +2. **From website**: Visit your blog frontend, click "Generate Post" button in toolbar +3. **View result**: Blog Publisher > Generation Log (inspect token usage, errors, or publish) -This project includes a MVC structure to help you get started with [Gitlab CI/CD components](https://docs.gitlab.com/ee/ci/components/). -The template provides the basic file structure to create your own single component. -This project should be public, or one of the jobs in the project's pipeline won't work. +### Topic Queue +- Blog Publisher > Topic Queue +- Create topics with priority (low / normal / high / urgent) +- Scheduler pulls pending topics in priority order +- Mark used/skipped after generation -## Licence +### Scheduled Generation +- Enable the hourly cron: Settings > Blog Publisher > Activate Scheduling +- Each active slot (morning/afternoon/evening) triggers at configured UTC time +- Auto-publishes if `auto_publish=True`, otherwise in draft -The licence can be changed. By default this project has the [MIT Licence](./LICENCE). - +## Development + +### Testing Framework +- **Unit tests**: `pytest-odoo` (TransactionCase) +- **BDD tests**: `pytest-bdd` (Gherkin features) +- **E2E tests**: Playwright (critical user journeys only) + +Run tests locally: +```bash +# All tests +pytest addons/itsulu_blog_publisher/tests/ -v + +# Single test class +pytest addons/itsulu_blog_publisher/tests/test_llm_router.py::TestLLMRouter -v + +# With coverage +pytest addons/itsulu_blog_publisher/tests/ --cov=addons/itsulu_blog_publisher + +# BDD features only +pytest addons/itsulu_blog_publisher/features/ -v +``` + +### Kubernetes CI/CD +The addon includes full Kubernetes test infrastructure: +- Template database priming (Odoo 17 init job) +- Ephemeral test job pods (auto-cleanup) +- PostgreSQL 15 persistent database +- GitLab Container Registry integration + +See [kubernetes/itsulu-testing/README.md](kubernetes/itsulu-testing/README.md) for setup details. + +## Architecture + +See [ARCHITECTURE.md](ARCHITECTURE.md) for: +- Data model specifications +- LLM router design +- Generation orchestration flow +- Settings and notification email format +- CI/CD infrastructure + +See [CLAUDE.md](CLAUDE.md) for: +- Odoo testing framework (TDD/BDD) +- Kubernetes test infrastructure gotchas +- Pre-commit hooks +- Failure recovery reference + +## Contributing + +We follow strict TDD discipline: +1. Write a failing test (show to reviewers) +2. Implement minimum code to pass +3. Refactor; test stays green +4. Run pre-commit hooks before submitting PR + +All code contributions must: +- Have > 80% test coverage on new code +- Pass `pre-commit run --all-files` +- Follow PEP 8 (via black, isort, flake8) +- Include descriptive test names (not just "test1, test2") + +See [CLAUDE.md](CLAUDE.md) for the complete TDD workflow. + +## Roadmap + +### Phase 1 (Current) +- ✅ Core generation orchestration +- ✅ Multi-LLM router +- ✅ Blog.post + social media model +- ✅ Schedule slots + cron dispatcher +- ✅ Settings + notification email +- ✅ Kubernetes test infrastructure +- 🔄 BDD/TDD test suite (in progress) + +### Phase 2 +- Image generation provider (DALL·E, Stable Diffusion) +- Coverage gates (≥80% on new code) +- Multi-language support +- Advanced scheduling (time zones, day-of-week patterns) + +### Phase 3 +- Playwright E2E journeys +- Performance regression testing +- Nightly smoke testing (CronJob) +- Runboat preview environment integration + +## License + +This addon is licensed under the LGPL v3.0. See [LICENSE](LICENSE) for details. + +## Support + +- **Issues**: https://github.com/itsulu/itsulu-blog-publisher/issues +- **Documentation**: See [CLAUDE.md](CLAUDE.md) and [ARCHITECTURE.md](ARCHITECTURE.md) +- **Testing Setup**: See [kubernetes/itsulu-testing/README.md](kubernetes/itsulu-testing/README.md) + +## Authors + +Built with ❤️ by [ITSulu](https://itsulu.com)