Auto Report — Product Specification

v1.0 — DraftPlatform: VENI-AI ShellPlan: Business+

1. Overview

What is Auto Report?

Auto Report is the organization's AI-powered reporting engine. Administrators configure report templates that define what data to collect and how it should be summarized. The system runs these reports on a schedule (daily, weekly, or monthly), uses an LLM to generate a readable narrative from the raw data, and delivers the finished report — PDF and web view — to designated recipients.

Why it exists

Organizations spend significant time each week manually gathering numbers from different systems, writing summaries, and formatting them into reports. Auto Report eliminates this work: once a template is configured, the report writes itself, on schedule, every time.

Who is it for?

Persona	What they do in Auto Report
Admin	Creates and manages report templates; configures schedules and recipients
Manager	Views reports delivered to them; triggers one-off runs
Viewer	Reads delivered reports; can download PDF
System (scheduler)	Automatically runs reports on the configured cron schedule

2. Goals & Non-Goals

Goals ✅

Define report templates: name, data source, prompt instructions, output format
Schedule reports: daily, weekly, or monthly (cron-based)
Generate reports using an LLM with org data as context
Deliver reports via in-app notification + email
Export any report as a PDF
View report history — all past runs for a template
Manually trigger a report run outside the schedule

Non-Goals ❌

Building custom data pipelines or ETL — data sources are predefined connectors
Interactive dashboards or live charts — reports are static snapshots
Real-time data streaming
Training or fine-tuning LLMs — only inference (generation)

3. User Stories

3.1 Create a report template

As an admin, I want to create a report template, so that the system knows what data to collect and how to summarize it.

Acceptance criteria:

I can set the template name, description, and target data source
I can write a prompt that tells the LLM how to summarize the data (e.g. "Summarize the top 5 sales activities this week in 3 bullet points")
I can select the output format: Narrative (paragraphs), Bullet Summary, or Table + Narrative
I can set the schedule: Daily at a specific time, Weekly on a chosen day, Monthly on a chosen date
I can choose who receives the report (individual users or roles)
Saving the template does not trigger an immediate run

3.2 View a scheduled report

As a manager, I want to receive and read a report that was automatically generated, so that I stay informed without manual effort.

Acceptance criteria:

I receive an in-app notification when a new report is ready
I can open the report and read the AI-generated content in a clean, formatted web view
The report shows: title, generation date, data period covered, and the AI narrative
I can see the raw data snapshot that was used as input (in a collapsible section)
The report is read-only

3.3 Export a report as PDF

As a manager, I want to download a report as a PDF, so that I can share it in meetings or attach it to emails.

Acceptance criteria:

Every report has a "Download PDF" button
The PDF matches the web view: title, date, narrative, tables (if any)
PDF includes the organization logo and a "Generated by VENI-AI Auto Report" footer
PDF generation completes in < 10 seconds for reports up to 5,000 words

3.4 Trigger a manual run

As an admin, I want to run a report immediately outside its schedule, so that I can get a fresh report before an important meeting.

Acceptance criteria:

Each template has a "Run Now" button in the template detail view
A manual run generates and delivers the report exactly as the scheduled run would
While the report is generating, the button shows "Generating…" and is disabled
If generation fails, I see an error message with the failure reason and a retry option
Manual runs are recorded in run history with a manual trigger label

3.5 View report history

As an admin, I want to see all past runs of a report template, so that I can compare results over time and investigate failures.

Acceptance criteria:

Each template has a "History" tab listing all past runs
Each row shows: run date, trigger (scheduled/manual), status (success/failed), generation time
I can click any successful run to open the full report
Failed runs show the error message
History is paginated (50 runs per page)

3.6 Edit or pause a template

As an admin, I want to pause a report template, so that it stops running while I update the configuration without deleting it.

Acceptance criteria:

I can toggle a template between Active and Paused states
Paused templates do not run on schedule but can still be triggered manually
I can edit all template fields (name, prompt, schedule, recipients) at any time
Editing does not affect past reports — only future runs use the new config
I can delete a template; deletion archives all its run history (not permanently purged)

4. Business Rules

Rule	Detail
Org isolation	Reports and templates are fully scoped to a single organization
LLM context limit	Data snapshots sent to the LLM are truncated to 16,000 tokens; a warning is shown if truncated
Run timeout	Each report run has a 3-minute hard timeout; timed-out runs are marked failed
Schedule minimum	Reports cannot be scheduled more frequently than once per hour
PDF retention	Generated PDFs are stored for 90 days, then automatically purged
Report history retention	Run metadata (without PDF) kept for 1 year
Recipient limit	Max 50 recipients per template
Template limit	Enforced per plan (e.g. Business: 20 templates, Enterprise: unlimited)

Auto Report
├── Home                    All report templates (Active / Paused)
│   └── [Template]          Template detail — config, history, Run Now
│       └── [Report Run]    Full report view — narrative, raw data, Download PDF
└── New Template            Template creation wizard

Screen: Template list (Home)

Element	Behaviour
Template card	Name, data source, schedule, last run date, status badge
Status badge	`Active` (green) / `Paused` (grey) / `Running` (spinning)
Run Now button	Triggers immediate generation
New Template button	Opens creation wizard

Screen: Report view

Element	Behaviour
Report header	Title, generated at date, period covered
AI narrative	Formatted text (headings, bullets, tables depending on format)
Raw data panel	Collapsible — shows the input snapshot fed to the LLM
Download PDF	Triggers server-side PDF render and download

6. Mockups

Screen A — Template List

auto-report.venizia.ai · Templates

Auto Report

📊 Templates

📋 All Reports

⚙️ Settings

Weekly Sales SummaryActive

Source: CRM · Every Monday 08:00 · Recipients: Sales Team (8)

Last run: Mon Mar 17 — Success · 34s

🕐 History✏️ Edit▶ Run Now

Monthly HR HeadcountActive

Source: HRM · 1st of month 07:00 · Recipients: HR Admin (2)

Last run: Mar 1 — Success · 52s

🕐 History✏️ Edit▶ Run Now

Daily Ops StandupPaused

Source: Ops DB · Daily 07:30 · Recipients: All Managers (5)

Last run: Mar 10 — Success · 28s

🕐 History✏️ Edit▶ Resume

Screen A — Template list: status badge · last run result · Run Now / Edit / History actions · Paused state

Screen B — Report View (Generated)

auto-report.venizia.ai · Weekly Sales Summary — Mar 17, 2025

Auto Report

📊 Templates

📋 Weekly Sales Summary

Executive Summary

This week the sales team closed 12 deals totaling $84,500 in new ARR, a 23% increase over the prior week. The Enterprise segment drove 65% of revenue. Three deals were lost to competitors — two cited pricing and one cited product gaps in reporting features.

Key Highlights

Top performer: Alice Smith — 4 deals, $32,000 ARR
Fastest close: TechCorp deal — 3 days from first contact to signed
Pipeline added: 18 new opportunities, estimated $120,000 potential ARR
Renewals: 5 renewals processed, 100% retention this week

Areas to Watch

SMB conversion rate dropped to 18% (from 27% last week). Two leads in the $5k–$10k range have been unresponsive for over 7 days — consider re-engagement campaigns.

📂 Raw data snapshot (used as LLM input)

{"period":"2025-03-10/2025-03-16","deals_closed":12,"total_arr":84500,"by_segment":{"enterprise":54925,"smb":29575},"lost_deals":3,"pipeline_added":18...}

Screen B — Report view: AI narrative · key highlights · collapsible raw data · Download PDF

Screen C — New Template Wizard

auto-report.venizia.ai · New Template

Auto Report

📊 Templates

➕ New Template

AI Prompt

Tell the AI how to summarize the data. Be specific about format, length, and what to focus on.

Summarize the week's sales performance for the leadership team. Include: total new ARR, number of deals closed, top performer by ARR, and any notable wins or losses. Use 3–4 bullet points followed by a 2-sentence recommendation. Keep the tone professional but concise.

NarrativeBullet SummaryTable + Narrative

← BackNext: Schedule →

Screen C — New Template wizard: step indicator · prompt editor · output format selector · navigation

Screen D — Run History

auto-report.venizia.ai · Weekly Sales Summary — History

Auto Report

📊 Templates

🕐 Run History

Date	Trigger	Status	Duration	Tokens used
Mar 17, 2025 08:04	Scheduled	Success	34s	3,241	View
Mar 14, 2025 10:22	Manual	Success	29s	2,980	View
Mar 10, 2025 08:01	Scheduled	Success	41s	3,512	View
Mar 3, 2025 08:00	Scheduled	✖ Failed	180s (timeout)	—	DetailsRetry

Screen D — Run History: scheduled vs manual trigger · success/failed status · token usage · View / Retry

7. Permissions (RBAC)

Permission	Resource	Action	Who has it by default
View reports	`reports`	`read`	All authenticated users (if recipient)
Download PDF	`reports`	`download`	All authenticated users (if recipient)
Trigger manual run	`reports`	`run`	Manager, Admin
Create / edit templates	`report_templates`	`manage`	Admin only
Delete templates	`report_templates`	`delete`	Admin only
View all reports (org-wide)	`reports`	`admin`	Admin only

8. Data Model

organizations
    │
    ├── report_templates (orgId, name, dataSource, prompt, outputFormat, schedule, status)
    │       │
    │       └── report_runs (templateId, triggeredBy, status, startedAt, finishedAt, tokensUsed)
    │                   │
    │                   ├── report_content (runId, narrative, rawDataSnapshot)
    │                   └── report_deliveries (runId, recipientId, deliveredAt, channel)
    │
    └── report_recipients (templateId, userId | roleId)

Table: `report_templates`

Column	Type	Notes
`id`	uuid	Primary key
`orgId`	uuid	Organization scope
`name`	text	Template display name
`description`	text?	Optional description
`dataSource`	text	e.g. `hrm`, `crm`, `ops_db`
`prompt`	text	LLM instruction for summarization
`outputFormat`	enum	`narrative`, `bullet_summary`, `table_narrative`
`schedule`	text	Cron expression (e.g. `0 8 * * 1` = Monday 08:00)
`status`	enum	`active`, `paused`
`createdBy`	uuid	Admin who created it
`updatedAt`	timestamp	—

Table: `report_runs`

Column	Type	Notes
`id`	uuid	Primary key
`templateId`	uuid	FK to template
`trigger`	enum	`scheduled`, `manual`
`triggeredBy`	uuid?	User ID for manual runs; null for scheduled
`status`	enum	`running`, `success`, `failed`
`startedAt`	timestamp	—
`finishedAt`	timestamp?	Null while running
`durationMs`	int?	Wall-clock time in ms
`tokensUsed`	int?	Tokens consumed by LLM
`errorMessage`	text?	Set on failure

Table: `report_content`

Column	Type	Notes
`id`	uuid	Primary key
`runId`	uuid	FK to report_runs
`narrative`	text	LLM-generated output
`rawDataSnapshot`	jsonb	Data sent as LLM context
`pdfPath`	text?	Storage path to generated PDF

9. API Endpoints

Templates

GET /api/report-templates — list all templates for the org

POST /api/report-templates — create a template

Body: { name, description?, dataSource, prompt, outputFormat, schedule, recipientIds[] }
Requires: report_templates:manage

PUT /api/report-templates/:id — update a template

PATCH /api/report-templates/:id/status — pause or resume

Body: { status: "active" | "paused" }

DELETE /api/report-templates/:id — delete template (archives runs)

Runs

POST /api/report-templates/:id/run — trigger a manual run

Requires: reports:run
Returns: { data: ReportRun } (status running)

GET /api/report-templates/:id/runs — list run history

Query	Type	Default
`limit`	int	50
`offset`	int	0

GET /api/report-runs/:id — get a single run with content

GET /api/report-runs/:id/pdf — download the generated PDF

Requires: reports:download
Streams the PDF file

10. Error Responses

json

{
  "error": {
    "code": "RUN_TIMEOUT",
    "message": "Report generation exceeded the 3-minute limit",
    "status": 504
  }
}

Code	Status	When
`RUN_TIMEOUT`	504	LLM call or data fetch exceeded 3 minutes
`DATA_SOURCE_UNAVAILABLE`	503	Target data source is unreachable
`CONTEXT_TRUNCATED`	200*	Data snapshot was truncated to fit LLM context (*warning in response body)
`TEMPLATE_PAUSED`	409	Manual run attempted on a Paused template
`TEMPLATE_LIMIT_REACHED`	402	Org has reached plan template limit
`PDF_NOT_READY`	404	PDF download requested before generation completed
`FORBIDDEN`	403	Missing required permission

11. Non-Functional Requirements

Requirement	Target
Report generation time (p95)	< 60 seconds per run
PDF generation time	< 10 seconds for reports ≤ 5,000 words
Scheduler precision	Runs start within ±2 minutes of scheduled time
LLM provider	Configurable (OpenAI GPT-4o default; swappable via env var)
Token cost visibility	Token count per run recorded; admin can see monthly total
Availability	99.5% for scheduler (allows brief downtime windows)
Concurrency	Up to 5 report runs executing in parallel per org

12. Out of Scope (v1)

Custom data connectors (v1 uses predefined sources: HRM, CRM, Ops DB)
Interactive charts or dashboards in the report view
Report commenting or collaborative annotations
Webhook delivery (email + in-app only in v1)
Multi-language report output
LLM fine-tuning on org data

13. Open Questions

#	Question	Owner	Status
1	Which LLM providers should be supported at launch?	Engineering	Open
2	Should cost per run be shown to org admins?	Product	Open
3	How should data sources authenticate to Auto Report?	Engineering	Open
4	Can reports be shared externally (public link)?	Product	Open
5	Should failed runs auto-retry, and how many times?	Engineering	Open
6	What is the token budget per run by plan tier?	Product	Open

Auto Report developer guide — implementation walkthrough
AI Assistant spec — RAG-based chatbot companion
RBAC reference — how permissions are enforced

Auto Report — Product Specification ​

1. Overview ​

What is Auto Report? ​

Why it exists ​

Who is it for? ​

2. Goals & Non-Goals ​

Goals ✅ ​

Non-Goals ❌ ​

3. User Stories ​

3.1 Create a report template ​

3.2 View a scheduled report ​

3.3 Export a report as PDF ​

3.4 Trigger a manual run ​

3.5 View report history ​

3.6 Edit or pause a template ​

4. Business Rules ​

5. Screens & Navigation ​

Screen: Template list (Home) ​

Screen: Report view ​

6. Mockups ​

Screen A — Template List ​

Screen B — Report View (Generated) ​

Screen C — New Template Wizard ​

Screen D — Run History ​

7. Permissions (RBAC) ​

8. Data Model ​

Table: report_templates ​

Table: report_runs ​

Table: report_content ​

9. API Endpoints ​

Templates ​

Runs ​

10. Error Responses ​

11. Non-Functional Requirements ​

12. Out of Scope (v1) ​

13. Open Questions ​

Auto Report — Product Specification

1. Overview

What is Auto Report?

Why it exists

Who is it for?

2. Goals & Non-Goals

Goals ✅

Non-Goals ❌

3. User Stories

3.1 Create a report template

3.2 View a scheduled report

3.3 Export a report as PDF

3.4 Trigger a manual run

3.5 View report history

3.6 Edit or pause a template

4. Business Rules

5. Screens & Navigation

Screen: Template list (Home)

Screen: Report view

6. Mockups

Screen A — Template List

Screen B — Report View (Generated)

Screen C — New Template Wizard

Screen D — Run History

7. Permissions (RBAC)

8. Data Model

Table: `report_templates`

Table: `report_runs`

Table: `report_content`

9. API Endpoints

Templates

Runs

10. Error Responses

11. Non-Functional Requirements

12. Out of Scope (v1)

13. Open Questions