User Guide¶

Templates¶

Templates are PowerPoint files with placeholders that get replaced with dynamic data.

Placeholder Syntax¶

Default markers are {{ and }} (configurable via MARKER_FRONT / MARKER_BACK).

{{title}}                    → simple replacement
{{context.company}}          → nested data
{{metrics.revenue}}          → dot notation
{{slides.0.title}}           → array access (0-based)

Placeholders work in text boxes, tables, grouped shapes, and image alt text.

Key Normalization¶

When data comes from AI workflows (structured context/result format), keys are normalized:

Input key	Placeholder
`Company Name`	`{{company-name}}`
`Executive_Summary`	`{{executive-summary}}`
`CO2 Reduction`	`{{co2-reduction}}`

Rules: spaces/dots/underscores become hyphens, lowercase, umlauts replaced, special chars removed.

Best practice: Use clean lowercase-hyphenated keys in your JSON to avoid surprises.

Image Replacement¶

Set a placeholder image's alt text to {{company-logo}}, then provide data as:

{"company-logo": {"bucket_name": "sf-images", "object_name": "uploads/uuid/logo.png"}}
{"company-logo": {"url": "https://example.com/logo.png"}}
{"company-logo": {"base64": "data:image/png;base64,iVBOR...", "filename": "logo.png"}}

Formatting¶

All font and paragraph formatting from the template is preserved. Replacement text supports basic markdown: **bold**, *italic*, [links](url). Use \n for line breaks.

Managing Templates¶

slidefactory template upload template.pptx --workflow-folder esg --name "ESG Template"
slidefactory template list --workflow-folder esg
slidefactory template placeholders 42          # extract & verify placeholders
slidefactory template download 42 --output template.pptx

Presentations¶

Generate¶

# Via CLI
slidefactory presentation generate --template-id 42 --data-file data.json --output-name "Report"

# Via API
curl -X POST http://localhost:8080/api/presentations/generate \
  -H "X-API-Key: sf_key" -H "Content-Type: application/json" \
  -d '{"template_id": 42, "data": {...}, "output_name": "Report"}'

Generation runs asynchronously via Celery. You get a process_id back immediately.

Track Progress¶

The API supports Server-Sent Events (SSE) for real-time progress:

GET /api/presentations/{process_id}/progress

Download¶

slidefactory presentation download proc_abc123 --output report.pptx
# Or via API: POST /api/presentations/{id}/download

Workflows¶

Workflows are orchestrated in N8N (or other engines). Slidefactory provides the API layer and template engine; N8N handles the business logic.

Browse & Execute¶

In the web UI (/app/workflows), you can browse available workflows, mark favorites, and trigger executions.

Via API:

# List workflows
curl -H "X-API-Key: sf_key" http://localhost:8080/api/workflows/navigation-workflows

# Execute
curl -X POST http://localhost:8080/api/workflows/n8n/{workflow_id}/execute \
  -H "X-API-Key: sf_key" -H "Content-Type: application/json" \
  -d '{"data": {...}}'

Favorites¶

Users can favorite workflows. Favorites are stored per user and shown on the dashboard.

Collections (RAG)¶

Upload documents for AI-powered retrieval-augmented generation.

# Upload document
curl -X POST http://localhost:8080/api/context/documents/upload \
  -H "X-API-Key: sf_key" -F "file=@report.pdf"

# Search
curl -X POST http://localhost:8080/api/context/documents/{id}/search \
  -H "X-API-Key: sf_key" -H "Content-Type: application/json" \
  -d '{"query": "climate initiatives", "top_k": 5}'

Documents are chunked (Jina AI), embedded, and stored in pgvector for similarity search.

Authentication¶

Three methods:

Method	Use case	Header
API Key	CLI, scripts, N8N	`X-API-Key: sf_...` or `Authorization: Bearer sf_...`
JWT	SPA frontend	`Authorization: Bearer eyJ...` (obtained via `/api/auth/login`)
Session	Web UI (cookie-based)	Automatic

Azure Entra (AD) SSO is supported for enterprise deployments.

Managing API Keys¶

slidefactory api-key create "My Key" --user-id 1 --scopes "*"
slidefactory api-key list

Managing Users¶

slidefactory user create-local user@example.com --name "Jane" --preset standard
slidefactory user list

User presets: admin (full access), standard (normal user), readonly.

Settings¶

The web UI settings page (/app/settings) provides:

User profile management (name, password)
Admin controls (user management, engine configuration)
Branding customization (logo, colors, title)