Survey Scribe¶

Extract questionnaire metadata with explicit provenance and bounded AI use.

Survey Scribe converts local questionnaire instruments into typed Survey Variable Information Schema (SVIS) artifacts. It provides native XLSForm extraction, model-assisted document extraction, caller-defined completed-form pipelines, source-grounded skip-pattern graphs, and versioned output.

Extract a questionnaire Deploy in Palantir Foundry Configure AI providers Browse DeepWiki

What the package provides¶

Questionnaire extraction¶

Extract native XLSForm instruments without a provider, or use a strict structured provider for PDF, DOCX, CSV, HTML, Markdown, and text.

Completed-form contracts¶

Use caller-defined Pydantic models for completed questionnaires. Answer-state, repeat assembly, and routing validation remain application responsibilities.

Skip patterns and routing¶

Represent activation, branches, section jumps, terminals, repeats, evidence, candidates, and review history without pretending to execute an interview.

Platform integration¶

Run a provider-free XLSForm transform in Palantir Foundry, use compatible Microsoft Foundry endpoints, or configure the generic mAI Factory gateway pattern.

Controlled providers¶

Configure OpenAI, OpenRouter, Vercel AI Gateway, Azure-compatible endpoints, Anthropic, or an application-owned StructuredProvider with bounded retries.

Verifiable artifacts¶

Write immutable generations with main output, sidecar diagnostics, manifests, checksums, and an active pointer.

Package scope¶

Survey Scribe 0.1.x is alpha software, with published releases available on PyPI. The source package includes:

Native instrument metadata extraction and provider-assisted extraction.
Stable legacy SVIS imports plus additive routed models and QuestionnaireRouter.
Typed configuration, result, source, routing, provider-contract, chunking, and serialization modules.
A PEP 561 py.typed marker for editors and type checkers.
A survey-scribe command for conversion, batch runs, provider/configuration inspection, and routing-schema export.

Local-first boundary

The installed package converts local files only. It does not accept remote URLs, store managed credentials, or expose a hosted inference service. Native XLSForm conversion can require zero provider calls. Other extraction sends normalized source content only to the provider endpoint that the user explicitly configures. The package contains no telemetry client.

Completed-questionnaire boundary

The standard client extracts instrument metadata, not respondent microdata. Custom structured pipelines can validate caller-defined answer records, but Survey Scribe does not classify skipped answers, execute routing conditions, or expand repeat instances.

Minimal example¶

from datetime import date

from survey_scribe.sources import SourceRegistry

conversion = SourceRegistry.default().convert_for_svis(
    "questionnaire.xlsx",
    extraction_date=date.today(),
)
if conversion.svis is None:
    raise RuntimeError("The workbook is not a supported XLSForm")

review_codes = tuple(item.code for item in conversion.document.diagnostics)
if conversion.native is not None:
    review_codes += tuple(item.code for item in conversion.native.diagnostics)
if review_codes:
    raise RuntimeError(f"Review XLSForm diagnostics before use: {review_codes}")

survey = conversion.svis