8.4 KiB
Agents, templates & response framework – checklist
Status of agents, prompts, content/schedule templates, and response shapes for campaigns, posts, and context in the PR/generation framework.
1. Response framework (request/response contract)
| Item | Status | Where |
|---|---|---|
| AgentResult (success, data, error) | ✅ Set | app/agent_responses.py |
| AgentError (code, message, details) | ✅ Set | same |
| ErrorCodes (VALIDATION_ERROR, NOT_FOUND, RENDER_FAILED, etc.) | ✅ Set | same |
| Agent-like endpoints return AgentResult | ✅ | preview, expand, expand-and-create, suggest-campaigns |
| Non-agent endpoints (lists) return plain JSON | ✅ | GET templates, GET schedule-templates, CRUD campaigns/posts |
Summary: All agent-style endpoints use the same response template (AgentResult). Campaign and post CRUD use their own response models (e.g. CampaignResponse, ScheduledPostResponse), not AgentResult, by design.
2. Context (product & features)
| Item | Status | Where |
|---|---|---|
| Product context (name, tagline, base_url) | ✅ Set | app/product_context.py (env: PRODUCT_NAME, PRODUCT_TAGLINE, PRODUCT_BASE_URL) |
| Feature catalog (id, name, path, value_prop) | ✅ Set | FEATURE_CATALOG – 14 features |
| GET /config/product-context | ✅ | app/product_context_api.py; optional ?include_config=1 for solar/battery |
| Context for templates (build_context_for_feature) | ✅ | app/content_templates.py – product_name, tagline, base_url, url, feature_*, today_kwh |
| Live-data enrichment (today_kwh) | ✅ | enrich_context_live_data() in content_templates; used when include_live_data=true in preview |
Summary: Context for campaigns and posts is fully defined: product + features + optional config and live data. No missing context pieces for the current flow.
3. Content templates (post copy)
| Template id | Platform | Placeholders | Status |
|---|---|---|---|
| feature_teaser_x | x | feature_name, value_prop, product_name, url | ✅ Set |
| feature_teaser_instagram | feature_name, product_name, value_prop, url | ✅ Set | |
| product_overview_x | x | product_name, tagline, base_url | ✅ Set |
| solar_today_x | x | today_kwh, product_name, base_url | ✅ Set |
Listing: GET /generate/templates returns all (id, name, description, platform, variables).
Rendering: POST /generate/preview-from-template (and expand-and-create) use these; response is AgentResult with data.text and data.context.
Summary: All content templates used by the framework are set. You can add more in content_templates.TEMPLATES if needed.
4. Schedule templates (when to post)
| Template id | Description | Status |
|---|---|---|
| weekdays_morning_evening | Mon–Fri 09:00 & 18:00 UTC, x + instagram | ✅ Set |
| weekdays_noon | Mon–Fri 12:00 UTC, x + instagram | ✅ Set |
| daily_evening | Every day 18:00 UTC, x + instagram | ✅ Set |
Listing: GET /generate/schedule-templates.
Expand: POST /generate/expand (body: campaign_id or start_date/end_date + schedule_template_id) returns AgentResult with data.slots, data.start_date, data.end_date.
Summary: Schedule templates for setting up campaign/post timing are set. No prompts; purely rule-based.
5. Agents and their request/response
| Agent | Endpoint / job | Request / input | Response (framework) | Status |
|---|---|---|---|---|
| Strategy | POST /generate/suggest-campaigns | Body: months_ahead, start_from?, features_per_campaign | AgentResult; data.campaigns[] | ✅ Set |
| Content (preview) | POST /generate/preview-from-template | Body: template_id, feature_id?, extra_context?, include_live_data?, location_id? | AgentResult; data.template_id, platform, text, context | ✅ Set |
| Content + schedule (expand) | POST /generate/expand | Body: campaign_id or start_date+end_date, schedule_template_id | AgentResult; data.slots, start_date, end_date | ✅ Set |
| Content + schedule + persist | POST /generate/expand-and-create | Body: campaign_id, schedule_template_id, content_template_id_x?, content_template_id_instagram?, feature_id? | AgentResult; data.created, slots_count, posts[] | ✅ Set |
| Publish | run_scheduled_posts_job (scheduler) | Due posts from DB | List of { post_id, status, posted_url?, error? } | ✅ Set |
| Analytics | run_post_insights_job (scheduler) | Posted posts with posted_url | { success, fetched, errors } | ✅ Set |
Summary: All agents that drive campaigns, posts, and context use a clear request/response contract. Publish and analytics are jobs (no HTTP request body); their response shape is fixed.
6. Campaign and post CRUD (setup)
| Area | Endpoints | Response shape | Status |
|---|---|---|---|
| Campaigns | POST/GET/PATCH/DELETE /campaigns, GET /campaigns/:id/calendar | CampaignResponse, list of | ✅ Set (not AgentResult) |
| Scheduled posts | POST/GET/PATCH/DELETE /scheduled-posts, POST /scheduled-posts/bulk, GET /limits | ScheduledPostResponse, list of | ✅ Set (not AgentResult) |
These are standard REST CRUD. They are not agent endpoints; they use their own response models. The framework for “setting up” campaigns and posts is: use suggest-campaigns for ideas → create campaign via POST /campaigns → use expand or expand-and-create with that campaign_id to fill posts. All of that is in place.
7. Prompts (AI / LLM)
| Item | Status | Note |
|---|---|---|
| AI system prompt (product context + limits) | ❌ Not implemented | Optional in architecture; would feed product_name, tagline, features, platform limits |
| AI suggest-posts endpoint (e.g. POST /generate/suggest-posts) | ❌ Not implemented | Would return suggested texts only; creation still via existing create/bulk |
| Prompt templates (e.g. “One tweet for feature X, max 280 chars”) | ❌ Not implemented | No LLM prompts in codebase |
Summary: All template-based generation (content + schedule) and the response templates (AgentResult) are set. AI prompts and an AI suggest-posts endpoint are not implemented; they are optional in the plan.
8. Quick reference: “Setting up campaigns & posts” via the framework
- Context – GET /config/product-context (and optional include_config).
- Ideas – POST /generate/suggest-campaigns → get suggested campaign names and dates (AgentResult).
- Create campaign – POST /campaigns (name, start_date, end_date, optional max_posts).
- Content options – GET /generate/templates; GET /generate/schedule-templates.
- Preview copy – POST /generate/preview-from-template (template_id, feature_id?, include_live_data?) → AgentResult with text and context.
- Slots only – POST /generate/expand (campaign_id or dates + schedule_template_id) → AgentResult with slots.
- Fill campaign with posts – POST /generate/expand-and-create (campaign_id, schedule_template_id, content_template_id_x/instagram, feature_id?) → AgentResult with created count and posts.
- Publish – Scheduler runs run_scheduled_posts_job; result shape is a list of { post_id, status, posted_url?, error? }.
- Analytics – run_post_insights_job returns { success, fetched, errors }.
Conclusion
- Agents: Strategy, content (preview + expand + expand-and-create), schedule (expand), publish job, analytics job – all set with clear behaviour and response shapes.
- Templates: Content templates (4) and schedule templates (3) are set; variables and placeholders are defined.
- Response templates: AgentResult (and ErrorCodes) are set and used for all generation/agent endpoints; campaigns/posts CRUD use their own response models by design.
- Context: Product context, feature catalog, and optional live data are set and exposed via /config/product-context and build_context_for_feature.
- Prompts: No AI/LLM prompts or suggest-posts endpoint are implemented; the framework is ready to add them later.
So: yes – for the current (non-AI) design, all agents, templates, and response templates used for setting up campaigns, posts, and context are set and consistent with the framework. The only optional part not implemented is AI prompts and an AI-based suggest-posts endpoint.