igny8/docs/20-API/AUTOMATION-ENDPOINTS.md

Automation Endpoints

Purpose

Describe automation API endpoints that configure, trigger, monitor, and control automation runs.

Code Locations (exact paths)

• Routing: backend/igny8_core/business/automation/urls.py
• Views: backend/igny8_core/business/automation/views.py
• Services/Tasks: backend/igny8_core/business/automation/services/automation_service.py, automation_logger.py, backend/igny8_core/business/automation/tasks.py

High-Level Responsibilities

• Expose configuration CRUD (get/update) and operational controls (run, pause, resume, cancel).
• Provide run history, status, logs, pipeline overview, credit estimate, and current processing state.
• Enforce site/account scoping and authentication.

Detailed Behavior

• Base path: /api/v1/automation/
• Key endpoints (actions on AutomationViewSet):
  • GET config?site_id= → get/create AutomationConfig for site (includes batch sizes, delays, schedule, flags, last/next run).
  • PUT update_config?site_id= → update config fields (enable, frequency, scheduled_time, batch sizes, delays).
  • POST run_now?site_id= → start a run (checks locks/credits) and enqueue Celery run_automation_task.
  • GET current_run?site_id= → current running/paused run details with per-stage results and totals.
  • GET history?site_id= → last 20 runs with status and timestamps.
  • GET logs?run_id=&lines= → tail of automation log file for run.
  • GET estimate?site_id= → estimated credits required plus current balance and sufficiency flag (1.2× buffer).
  • GET pipeline_overview?site_id= → counts/pending by stage across planner/writer models.
  • GET current_processing?site_id=&run_id= → live processing state for active run.
  • POST pause?run_id= / POST resume?run_id= / POST cancel?run_id= → control run state (pause/resume/cancel).
• Permissions/tenancy: IsAuthenticated; site fetched with account=request.user.account; automation lock is per site; request.account set by middleware.

Data Structures / Models Involved (no code)

• AutomationConfig, AutomationRun, planner models (Keywords/Clusters/ContentIdeas), writer models (Tasks/Content/Images).

Execution Flow

• View actions call AutomationService to start/control runs; long-running work executed by Celery tasks (run_automation_task, resume_automation_task).
• Config updates persist to DB; run state and logs updated as stages progress.

Cross-Module Interactions

• Uses planner/writer data for counts and processing; AI functions run inside service; billing credits checked via account balance before start and inferred from AI task logs during execution.

State Transitions

• Run status: running ↔ paused → completed/failed/cancelled; current_stage advances per stage; per-stage results stored in AutomationRun.
• Config last_run_at/next_run_at updated on scheduled runs.

Error Handling

• Missing site_id/run_id → 400; run not found → 404; insufficient credits or concurrent run → 400; server errors → 500.
• Logs endpoint 404s when run missing.

Tenancy Rules

• All operations scoped to the authenticated user’s account/site; no cross-tenant access; locks are per site.

Billing Rules

• Start requires credits ≥ estimated * 1.2; credits consumed by AI tasks are recorded via AI task logs and aggregated per stage.

Background Tasks / Schedulers

• Celery tasks for scheduled runs (check_scheduled_automations) and pipeline execution/resume.

Key Design Considerations

• Cooperative pause/resume/cancel with persisted partial results.
• Log access via filesystem tail; structured per-stage results stored in DB for quick status reads.

How Developers Should Work With This Module

• Trigger runs via run_now; avoid bypassing locks/credit checks.
• Extend actions by reusing AutomationService and Celery tasks; keep site scoping and error handling consistent.