Nicholas Riegel
087c21a860
Replace generic GitLab CI template with complete Odoo addon documentation including features, installation, configuration, development workflow, testing framework, Kubernetes CI/CD setup, and contributing guidelines.
193 lines
6.4 KiB
Markdown
193 lines
6.4 KiB
Markdown
# ITSulu Blog Publisher
|
|
|
|
AI-powered blog post generation for Odoo with multi-LLM support, scheduling, and social media integration.
|
|
|
|
## 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.
|
|
|
|
## 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
|
|
|
|
## Requirements
|
|
|
|
### Odoo Version
|
|
- **Target**: Odoo 17.0 Community (development branch)
|
|
- **Planned**: Odoo 14.0 Community (separate branch for App Store)
|
|
|
|
### 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
|
|
```
|
|
|
|
### Docker (Testing)
|
|
|
|
```bash
|
|
docker build -t itsulu-blog-publisher:latest .
|
|
docker run -p 8069:8069 itsulu-blog-publisher:latest
|
|
```
|
|
|
|
## 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
|
|
|
|
## Usage
|
|
|
|
### 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)
|
|
|
|
### 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
|
|
|
|
### 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
|
|
|
|
## 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)
|