Skip to main content

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:

  1. Takes your survey_question parameter
  2. Injects survey-specific framing: "A respondent was asked: '{survey_question}'."
  3. Delegates to cat-stack for 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)

Source distribution for cat-survey 0.4.0
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)

Table of built distributions (wheels) for cat-survey 0.4.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page