cat-survey
Survey response classification powered by LLMs. A thin, survey-specific wrapper around cat-stack.
cat-survey adds survey-specific prompt framing ("A respondent was asked: ...") on top of the domain-agnostic cat-stack engine — giving LLMs the context that responses come from a survey instrument.
Installation
pip install cat-survey
With optional extras:
pip install "cat-survey[pdf]" # PDF survey processing
pip install "cat-survey[embeddings]" # Embedding-based similarity scoring
pip install "cat-survey[agent]" # Claude-subscription backend (model_source="claude-agent")
pip install "cat-survey[codex-agent]" # ChatGPT-subscription backend (model_source="codex-agent")
The subscription backends authenticate through your Claude or ChatGPT plan instead of a metered API key — pass model_source="claude-agent" (or "codex-agent") and leave api_key unset. model_source="claude-code" (the Claude Code CLI, if installed) needs no extra at all.
Quick Start
Classify survey responses
import catsurvey
results = catsurvey.classify(
input_data=["I feel great about the program", "It was a waste of time"],
categories=["Positive", "Negative", "Neutral"],
survey_question="How do you feel about the new wellness program?",
api_key="sk-...",
)
Discover categories from open-ended responses
result = catsurvey.extract(
input_data=responses,
api_key="sk-...",
survey_question="What changes would you suggest for the workplace?",
)
print(result["top_categories"])
For finer control, run the two stages yourself: explore() builds a
frequency-ranked inventory of raw category labels, and collapse_themes()
(re-exported from the cat-stack engine) consolidates it into a deduplicated
taxonomy — string-similarity and embedding pre-merge, quality-controlled LLM
merge passes, and an optional count-guided reduction to the top_n most
common categories. extract() chains these two stages for you.
raw_labels = catsurvey.explore( # list[str]: every label, with repeats
input_data=responses,
api_key="sk-...",
survey_question="What changes would you suggest for the workplace?",
)
themes = catsurvey.collapse_themes( # list[str]: consolidated taxonomy
input_data=raw_labels,
api_key="sk-...",
description="What changes would you suggest for the workplace?",
top_n=12,
)
Summarize responses
summaries = catsurvey.summarize(
input_data=responses,
api_key="sk-...",
description="Open-ended feedback from employee satisfaction survey",
)
How It Works
cat-survey is a thin wrapper that:
- Takes your
survey_questionparameter - Injects survey-specific framing: "A respondent was asked: '{survey_question}'."
- Delegates to
cat-stackfor all LLM communication, classification logic, batch processing, and ensemble methods
All cat-stack parameters (multi-model ensemble, batch mode, chain-of-thought, etc.) are passed through via **kwargs.
API
| Function | Description |
|---|---|
classify() |
Classify responses into predefined categories |
extract() |
Discover and normalize categories from responses |
explore() |
Raw category extraction (no deduplication) |
collapse_themes() |
Consolidate an explore() inventory into a deduplicated taxonomy (re-export from cat-stack) |
summarize() |
Summarize responses (pass-through to cat-stack) |
Ecosystem
| Package | Role |
|---|---|
| cat-stack | Domain-agnostic LLM classification engine |
| cat-survey | Survey-specific wrapper (this package) |
| cat-cog | Cognitive assessment scoring (CERAD) |
License
GPL-3.0-or-later
Metadata
Release files for cat-survey 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| cat_survey-0.4.0.tar.gz | 17.1 kB | Without provenance | Details for cat_survey-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cat_survey-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for cat_survey-0.4.0-py3-none-any.whl |
Total release size: 37.3 kB
Release files / cat_survey-0.4.0.tar.gz
| Download URL | cat_survey-0.4.0.tar.gz |
|---|---|
| Size | 17.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
909b11ea3e520ae7e41cb60d65ff8e1d53acdd9ea2c884f448b35f83d54ca387
|
|
BLAKE2b-256 checksum How to use checksums |
3e7f85857eabbcd565e25423149115bc4d6187b859f582f9782533ee3f0b0768
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.7 {"installer":{"name":"uv","version":"0.10.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / cat_survey-0.4.0-py3-none-any.whl
| Download URL | cat_survey-0.4.0-py3-none-any.whl |
|---|---|
| Size | 20.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b27db58b51488a7fb97de349fb2299f9fbc891d5bb6f861f7da6c4ff40521ccb
|
|
BLAKE2b-256 checksum How to use checksums |
a3fc41acde13bb4fe5d272705978de141957021ef788cd581b33aef032d69a26
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.7 {"installer":{"name":"uv","version":"0.10.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for cat-survey 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.