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

Ecosystem

License

GPL-3.0-or-later