itsulu/itsulu-blog-publisher
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: add comprehensive project README with features and usage guide

Browse source 
Replaced GitLab CI template README with complete ITSulu Blog Publisher
documentation including:

- Project overview and core features
- 4 supported LLM providers (Claude, ChatGPT, Gemini, Ollama)
- Test coverage summary (63/63 tests passing)
- Installation and setup instructions
- Usage guide for on-demand and scheduled generation
- Configuration parameters reference
- Architecture overview with models and services
- Development workflow and TDD patterns
- Troubleshooting section
- Phase 2 completion status

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
This commit is contained in:
Nicholas Riegel 2026-05-30 00:46:19 -04:00
parent 0a795a1c97
commit eebc86f326
1 changed files with 246 additions and 33 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

279
README.md
View file

@ -1,52 +1,265 @@
# Gitlab component template # ITSulu Blog Publisher — Odoo 17 Addon
<!-- Automated blog post generation and publishing for Odoo 17 Community Edition, powered by generative AI (Anthropic Claude, OpenAI, Google Gemini, or Ollama).
Update this readme with your component details. Replace content in `< >` with your project information.
For more information:
- How to create a CI/CD component: https://docs.gitlab.com/ee/ci/components/#write-a-component ## Features
- How to write a clear README.md file: https://docs.gitlab.com/ee/ci/components/#write-a-clear-readmemd
- CI/CD Component security best practices: https://docs.gitlab.com/ee/ci/components/#cicd-component-security-best-practices
-->
<!-- Uncomment and update the following link to display a release badge: https://docs.gitlab.com/ee/user/project/badges.html#latest-release-badges --> ### ✨ Core Functionality
<!-- [![Latest Release](https://gitlab.com/<your project path>/-/badges/release.svg)](https://gitlab.com/<your project path>/-/releases) -->
## Components - **On-Demand Generation** — Wizard-driven blog post creation via backend form
- **Scheduled Generation** — Three configurable daily cron slots (morning, afternoon, evening)
- **Multi-Provider LLM** — Route requests to Anthropic Claude, OpenAI ChatGPT, Google Gemini, or local Ollama models
- **SEO Automation** — Auto-populate meta titles, descriptions, keywords, and tags
- **Social Media Copy** — Generate platform-specific posts for X, BlueSky, Mastodon, and LinkedIn
- **Auto-Publish** — Publish generated posts immediately or save as drafts for review
- **Topic Queue** — Priority-based topic queue for scheduled generation
- **Notification Emails** — Automated emails with generated content and social copy
- **Generation Audit Trail** — Complete logs with token usage, provider, model, and error tracking
- **Error Recovery** — Retry button on failed generation logs
### `<Component-name>` ### 🧠 Supported LLM Providers
Use this component to `<component-description>`. | Provider | Model Examples | Config Parameter |
|----------|---|---|
| **Anthropic Claude** | claude-sonnet-4-20250514, claude-opus-4-1 | `itsulu_blog_publisher.anthropic_api_key` |
| **OpenAI** | gpt-4o, gpt-4-turbo | `itsulu_blog_publisher.openai_api_key` |
| **Google Gemini** | gemini-2.0-flash, gemini-pro | `itsulu_blog_publisher.gemini_api_key` |
| **Ollama** | Any local model (mistral, llama2, etc.) | `itsulu_blog_publisher.ollama_base_url` |
To add this component to your CI/CD pipeline, add the following include entry to your ### 📊 Test Coverage
project's CI/CD configuration:
```yaml **Phase 2 Complete**: 63 automated tests across 6 test files
include:
- component: https://gitlab.com/<your project path>/<name of your template>@<tag> | Test Suite | Count | Status |
|---|---|---|
| Unit Tests (TDD) | 48 | ✅ All Passing |
| Behavior Tests (BDD) | 15 | ✅ All Passing |
| **Total** | **63** | **100% ✅** |
**Coverage Areas**:
- Topic queue management (7 tests)
- Generation audit logs (8 tests)
- Social media copy (16 tests)
- Schedule slots (10 tests)
- LLM router dispatch (7 tests)
- E2E workflows (15 BDD scenarios)
## Installation
### Prerequisites
- Odoo 17.0 Community
- Python 3.10+
- PostgreSQL 13+
- pip packages: `requests`, `pytest-odoo`, `pytest-bdd`
### Steps
1. **Clone the repository** into your Odoo addons directory:
```bash
git clone https://github.com/itsulu-odoo/itsulu-blog-publisher.git \
/path/to/odoo/addons/itsulu_blog_publisher
``` ```
Where `<tag>` is the release tag you want to use ([releases list](https://gitlab.com/<your-project-path>/-/releases)). 2. **Install Python dependencies**:
```bash
pip install requests
```
## Inputs 3. **Install the addon** in Odoo (UI or CLI):
```bash
odoo -d mydb -i itsulu_blog_publisher --stop-after-init
```
The template contains some optional [inputs](https://docs.gitlab.com/ee/ci/yaml/inputs.html): 4. **Configure API keys** in Odoo Settings → Technical → Parameters:
- `itsulu_blog_publisher.anthropic_api_key` (if using Claude)
- `itsulu_blog_publisher.openai_api_key` (if using OpenAI)
- `itsulu_blog_publisher.gemini_api_key` (if using Gemini)
- `itsulu_blog_publisher.ollama_base_url` (if using Ollama, e.g., `http://localhost:11434`)
<!-- Add or update rows if you change the inputs in the template --> 5. **Configure notification emails** in Settings:
- `itsulu_blog_publisher.notification_emails` (comma-separated list)
| Input | Default value | Description | ## Usage
|------------|------------------|-------------|
| `job_name` | `job-template` | The job name. | ### 1. Create a Blog Post On-Demand
| `image` | `busybox:latest` | The container image to use to run the job. |
| `stage` | `test` | The stage name for the job. | 1. Go to **Blog** → **Blog Publisher** → **Generate Now**
2. Enter topic/prompt
3. Select LLM provider and model
4. Choose auto-publish or draft
5. Click **Generate**
The addon will:
- Call the selected LLM provider
- Create a blog.post with generated title, body, SEO fields
- Generate social media copy for enabled platforms
- Send notification email if published
- Log tokens used, provider, model, and generation time
### 2. Schedule Automatic Generation
1. Go to **Blog** → **Blog Publisher** → **Schedule Slots**
2. Create/configure 3 slots: Morning, Afternoon, Evening
3. Set trigger time (UTC hours)
4. Choose LLM provider and model per slot
5. Enable auto-publish or save as draft
6. Save and activate
The system will:
- Run active slots at configured times via cron
- Pull next topic from queue (if available) or LLM-chosen topic
- Publish immediately or save for review
- Send notification emails for published posts
### 3. Manage Topic Queue
1. Go to **Blog** → **Blog Publisher** → **Topics**
2. Create topics with title, notes, and priority (Urgent/High/Normal)
3. Set state to "Pending"
4. During generation, slots will consume pending topics in priority order
5. Topics move to "Used" state after generation
### 4. Monitor Generation Logs
1. Go to **Blog** → **Blog Publisher** → **Generation Logs**
2. View all generation attempts (success/error)
3. Check tokens used, provider, model, duration
4. Retry failed generations using **Retry** button
## Configuration
### Settings
| Parameter | Type | Default | Description |
|---|---|---|---|
| `itsulu_blog_publisher.notification_emails` | Char | (empty) | Comma-separated email addresses for notifications |
| `itsulu_blog_publisher.anthropic_api_key` | Char | (empty) | Anthropic API key for Claude models |
| `itsulu_blog_publisher.openai_api_key` | Char | (empty) | OpenAI API key for ChatGPT models |
| `itsulu_blog_publisher.gemini_api_key` | Char | (empty) | Google Gemini API key |
| `itsulu_blog_publisher.ollama_base_url` | Char | (empty) | Base URL for local Ollama server |
### Email Template
The addon includes a pre-configured email template (`email_template_blog_published`) that:
- Displays blog post title and metadata
- Includes social media copy for each enabled platform
- Links to the published post
- Shows generation stats (tokens, model, time)
Customize by editing the template in **Email** → **Email Templates**.
## Architecture
### Models
- **itsulu.blog.topic** — Topic queue with priority and state
- **itsulu.blog.generation.log** — Audit trail for all generation attempts
- **itsulu.blog.post.social** — Social media copy linked to blog posts
- **itsulu.blog.schedule** — Configurable cron slots for scheduled generation
### Services
- **llm_router.py** — Dispatcher that routes requests to provider APIs
- **anthropic_provider.py** — Anthropic Claude integration
- **openai_provider.py** — OpenAI ChatGPT integration
- **gemini_provider.py** — Google Gemini integration
- **ollama_provider.py** — Local Ollama model integration
- **image_router.py** — Optional cover image generation (DALL·E, Imagen, Stable Diffusion)
## Development
### Running Tests
```bash
# All tests
pytest addons/itsulu_blog_publisher/tests/ -v
# Specific test file
pytest addons/itsulu_blog_publisher/tests/test_blog_topic.py -v
# Specific test
pytest addons/itsulu_blog_publisher/tests/test_blog_topic.py::TestBlogTopicPriority::test_get_next_topic_returns_highest_priority_pending_topic -v
# BDD scenarios only
pytest addons/itsulu_blog_publisher/tests/test_bdd_steps.py -v
```
### TDD Workflow
This project follows strict TDD discipline (see [CLAUDE.md](CLAUDE.md)):
1. **RED** — Write failing test
2. **GREEN** — Write minimum code to pass
3. **REFACTOR** — Clean up while test stays green
4. **REPEAT** — Next feature
### Code Quality
Pre-commit hooks enforce:
- Black code formatting
- isort import sorting
- pylint-odoo linting
Run before committing:
```bash
pre-commit run --all-files
```
## Troubleshooting
### "Configuration error: API key not configured"
**Cause**: API key parameter not set in Settings
**Solution**: Go to Settings → Technical → Parameters and add the required key for your LLM provider
### "Unknown provider: <name>"
**Cause**: Provider name misspelled or provider not supported
**Solution**: Use one of: `anthropic`, `openai`, `gemini`, `ollama`
### "No blog.post record was created"
**Cause**: LLM response parsing failed or validation error
**Check**: Generation log for error message; verify LLM response format
### "No email sent for published post"
**Cause**: Notification email template not found or recipients not configured
**Solution**:
1. Ensure template exists: **Email** → **Email Templates** → "Blog Post Published"
2. Set notification emails: **Settings** → Technical → Parameters → `itsulu_blog_publisher.notification_emails`
## Documentation ## Documentation
This project includes a MVC structure to help you get started with [Gitlab CI/CD components](https://docs.gitlab.com/ee/ci/components/). - [CLAUDE.md](CLAUDE.md) — Complete TDD framework, testing patterns, troubleshooting
The template provides the basic file structure to create your own single component. - [ARCHITECTURE.md](ARCHITECTURE.md) — System design, data flow, API contracts
This project should be public, or one of the jobs in the project's pipeline won't work. - [PHASE2_ROADMAP.md](PHASE2_ROADMAP.md) — Phase 2 implementation status
## Licence ## License
The licence can be changed. By default this project has the [MIT Licence](./LICENCE). MIT License. See [LICENSE](LICENSE) for details.
<!-- You should update the year and name in the license file. -->
## Support
For issues, feature requests, or questions, open an issue on GitLab:
https://gitlab.com/itsulu-odoo/itsulu-blog-publisher/issues
## Roadmap
### Phase 3 (Runboat E2E)
- Playwright end-to-end scenarios
- UI-driven generation workflow testing
- Multi-user collaboration scenarios
### Phase 4 (Performance & Scale)
- Query optimization (N+1 detection)
- Batch generation for multiple topics
- Template caching and pre-rendering
- Performance benchmarks (throughput, latency)
---
**Current Status**: Phase 2 Complete ✅ (63/63 tests passing)
**Last Updated**: 2026-05-30
**Maintainer**: Nicholas Riegel (nicholasr@itsulu.com)