solar/docs/AGENT_RESPONSE_FRAMEWORK.md

Agent response framework

All PR/generation agent-like endpoints return a consistent response shape so callers can handle success and error without guessing. This keeps failure modes low and avoids raw exceptions or missing fields.

Shape

Every agent response is an AgentResult (see backend/app/agent_responses.py):

{
  "success": true,
  "data": { ... },
  "error": null
}

or on failure:

{
  "success": false,
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable message",
    "details": { "key": "value" }
  }
}

• success – true if the agent completed without error; otherwise false.
• data – Payload when success is true (structure depends on endpoint).
• error – When success is false: code (machine-readable), message (human), optional details.

Error codes

Code	Meaning
VALIDATION_ERROR	Invalid input (dates, missing fields, etc.)
NOT_FOUND	Campaign, template, or resource not found
RENDER_FAILED	Template render failed (unknown template, missing variable)
EXTERNAL_SERVICE_ERROR	Dependency (e.g. browser, API) failed
CONFIG_MISSING	Required config not set

Endpoints using AgentResult

• POST /generate/preview-from-template – data: { template_id, platform, text, context }. Optional body include_live_data: true enriches context with today_kwh from stored metrics.
• POST /generate/expand – data: { slots, start_date, end_date }.
• POST /generate/expand-and-create – data: { created, slots_count, posts[] } or { created: 0, message, posts: [] }.
• POST /generate/suggest-campaigns – data: { campaigns: [{ name, start_date, end_date, suggested_feature_ids }] }. Body: months_ahead, start_from (YYYY-MM-DD), features_per_campaign.
• POST /generate/suggest-posts – data: { posts: [{ platform, text, feature_id?, source: "llm" }] }. Body: platform, optional feature_id, topic, campaign_name, tone, count. On config/network errors returns CONFIG_MISSING or EXTERNAL_SERVICE_ERROR.

Non-agent endpoints

• GET /generate/templates – Returns a list (no AgentResult).
• GET /generate/schedule-templates – Returns a list (no AgentResult).

Publish job result

The scheduled-posts job (run_scheduled_posts_job) returns a list of per-post results (not AgentResult, because it is not an HTTP endpoint):

• { "post_id": 1, "status": "posted", "posted_url": null }
• { "post_id": 2, "status": "failed", "error": "..." }

Analytics job result

run_post_insights_job returns a dict with a fixed shape:

• { "success": true, "fetched": n, "errors": [] }
• or { "success": false, "fetched": 0, "errors": [ { "message": "..." } ] }

Usage in clients

1. Parse JSON.
2. If success === false, use error.message (and optionally error.code, error.details) for UX or logging.
3. If success === true, use data for the payload.

Never assume data is present when success is false, or that error is present when success is true.