feat: AI survey draft generation from a creator brief (#15) - #59
Open
ganjasan wants to merge 6 commits into
Open
feat: AI survey draft generation from a creator brief (#15)#59ganjasan wants to merge 6 commits into
ganjasan wants to merge 6 commits into
Conversation
One tracked file carries the design rules with citations (Brown & Kyttä 2014; Seebauer 2024; Lehnert 2023; Alderton 2026; Laborgne & Klöcker 2023) plus a description of what a respondent actually sees. The AI generator prompt and the newsurvey skill are both operative summaries of it — change a rule there and here together. Source papers and heat-domain notes stay untracked: the repo is public, the notes carry client context and the PDFs are third-party copyright. The newsurvey skill gains the same design guidance: it previously knew how to assemble a valid ZIP but nothing about what makes a survey collect. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
New survey/ai/ package: LLMProvider interface (Anthropic via the official SDK, Gemini over plain requests for free-tier testing), a PPGIS-grounded prompt, a pure validator that gates model output before any DB write, and a materializer that computes every structural field (codes, is_head, section links, order) from list order — the model only ever produces content, so the serialization import's silent gotchas are unreachable by construction. Marker color and a curated-enum icon are part of the schema: an all-black-marker draft reads as unfinished, and a free-text icon field would let the model hallucinate FA classes that silently render nothing. AIGenerationEvent doubles as async task state and the hypothesis-telemetry record: brief, generated blob snapshot (baseline for the generated-vs-published diff), token usage, latency, outcome, last_polled_at/redirected_at (waited-or-left, measured server-side). check_quota() is the documented no-op seam for plans & entitlements (#87). Pipfile.lock regenerated: adds anthropic; also picks up nh3, which was in Pipfile but missing from the lock. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The create page gains an optional brief (goal, audience, map target, use-case chips) rendered only when a provider is configured. Generate enqueues a Celery task and shows a fixed overlay with rotating game-style quips; the page polls a status endpoint that answers 204 while pending (swapping the overlay every tick made the screen flicker) and HX-Redirects into the populated editor on success. Validation failures return a fragment, never the full page — swapping survey_create.html into the HTMX slot would duplicate every id and re-run the Leaflet setup. /editor/ now redirects creators whose org has no surveys to the create page (?dashboard=1 escapes; viewers exempt — they cannot create). Layout compacted so the whole form, map and actions fit one desktop screen; Generate sits on its own row above Create empty and Cancel. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…b+worker Worker previews were off as pure cost; AI draft generation runs in the worker, and a preview without one would leave the feature untestable exactly where changes are reviewed. The key is sync:false on both services (web only gates the UI on its presence; the worker makes the calls). Ports registry records offset 70 for this worktree. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
54 tests over the generation pipeline: validator rules (languages, geo policy, codes, styling), computed structure and rollback, provider config gating and error normalization (incl. Gemini schema dialect and truncation usage), the retry-once loop, view gating and the 204-pending/HX-Redirect contract, the zero-survey redirect, task crash-survivability, and the waited-or-left stamps. Two pre-existing dashboard tests now pass ?dashboard=1 — their orgs have no live surveys, so a bare /editor/ correctly redirects to the create page. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…low-up Full artifact set (proposal, design with 10 decisions, delta specs for ai-survey-generation / survey-editor / render-deployment, tasks) plus the interaction-mode mockups that drove the variant-B decision. Backlog: #15 marked promoted; new #124 'AI activation analytics' captures the hypothesis instrument's second half (funnel dashboard section, generated-vs-published diff, client events, fork-friendly replay/experiments stack). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
ganjasan
deployed
to
feature/ai-survey-generator - mapsurvey-db PR #59
August 14, 2026 18:01 — with 
Render
Active
Render
Active
ganjasan
deployed
to
feature/ai-survey-generator - mapsurvey-celery PR #59
August 14, 2026 18:02 — with
Render
Active
Render
Active
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements backlog #15 — AI agent that creates surveys from chat description (MVP: one-shot brief, mockup variant B). OpenSpec change:
openspec/changes/ai-survey-generator/.What this does
The Create New Survey page gains an optional AI brief (goal, audience, what to map, use-case chips). "Generate draft" runs a Celery task that calls an LLM, validates the output, and materializes a fully populated multilingual survey through the existing serialization import path; the page shows a game-style loading overlay and lands the creator in the editor with a working draft. Creators whose org has no surveys are routed from
/editor/straight to the create page (?dashboard=1escapes).Rationale: of 222 real registrations only 53% ever create a survey — the empty editor is the funnel's biggest leak.
Design highlights
code,is_head, section links andorder_numbercome from list order, so the import path's silent gotchas (stuck-in-draft, broken navigation, code collisions) are unreachable by construction.survey/ai/client.py): Anthropic (official SDK, defaultclaude-opus-5) and Gemini (plainrequests, free-tier testing; schema adapted to its JSON-Schema dialect). Adding an EU-hosted or local provider is one class — proven by the Gemini addition touching onlyclient.py.docs/research/survey-design-rules.md(Brown & Kyttä 2014; Seebauer et al. 2024; Lehnert et al. 2023; Alderton et al. 2026) plus a description of the respondent-facing interface. Marker color + curated-enum icon are part of the schema.AIGenerationEvent= async task state + hypothesis telemetry: brief, generated-blob snapshot (baseline for the generated-vs-published diff), tokens/latency/outcome, and server-sidelast_polled_at/redirected_at(waited-or-left, no client JS). Quota seam (check_quota) documented for #87.Verified
?dashboard=1(their orgs have no live surveys, so the new redirect correctly fires).gemini-3.6-flash): two-language (en+it) drafts generated in 19–44s; exactly onepointquestion with styled marker (#D9480F,fas fa-exclamation-triangle) and popup sub-questions; translations complete; coping-behaviour question present (the PPGIS rule visibly changed the output).hx-swap="none"element, pending answers 204), HX-Redirect into the populated editor, one-screen layout.Known gaps
Deploy notes
0048, new table only).ANTHROPIC_API_KEY(orAI_PROVIDER=gemini+GEMINI_API_KEY) in the Render dashboard on web and worker; unset = the panel simply doesn't render.render.yamlnow creates worker instances for PR previews (small prorated cost).🤖 Generated with Claude Code