S8u281m/governance-research-app

Qualitative Coding with Claude API

A Streamlit application for systematic qualitative coding of interview transcripts using Claude API, designed for Atlas.ti integration.

Features

• —Persistent Configuration: One-time setup for codebook and API credentials
• —Transcript Parsing: Intelligent parsing of conversational interview formats
• —Contextual Coding: Maintains interviewer-interviewee context for better accuracy
• —Reproducible Results: Fixed parameters and logging for consistency
• —Quality Control: Validation and confidence thresholds
• —Atlas.ti Export: QDPX-compatible format for seamless integration

Quick Start

1. Initial Setup (One-time)

API Configuration:

• —Enter your Anthropic API key in the sidebar
• —Select your preferred Claude model
• —Save configuration (persists across sessions)

Codebook Setup:

• —Prepare your codebook in JSON format:

[
  {
    "name": "EMOTIONAL_RESPONSE",
    "definition": "Expressions of emotional reactions to events",
    "key_indicators": "feeling words, emotional descriptions",
    "manifestation": "I felt..., It made me..., emotionally charged language",
    "guidelines": "Code only explicit emotional expressions, not inferred emotions"
  },
  {
    "name": "DECISION_MAKING",
    "definition": "Descriptions of decision-making processes",
    "key_indicators": "choice, decision, considering, weighing options",
    "manifestation": "I decided..., I chose..., I had to decide...",
    "guidelines": "Include both individual and collaborative decisions"
  }
]

• —Paste in the codebook section and save

2. Upload Transcript

Format Requirements:

Shubham Sharma: What was your experience with the new system?
Participant 1: Well, I found it quite intuitive at first, but then I started having some issues with the interface.
Shubham Sharma: Can you tell me more about those issues?
Participant 1: The main problem was that the navigation wasn't clear, and I often got lost trying to find specific features.

3. Configure Settings

• —Interviewer Name: Default "Shubham Sharma" (update if different)
• —Max Tokens per Chunk: 3000 (adjust for longer responses)
• —Confidence Threshold: 0.7 (filter low-confidence codes)

4. Run Analysis

• —Click "Start Coding Analysis"
• —Monitor progress bar
• —Review results and statistics

5. Export Results

• —Generate QDPX format for Atlas.ti import
• —Download coding results with timestamps
• —Review detailed coding decisions

Advanced Features

Reproducibility Controls

• —Fixed Model Parameters: Temperature 0.1, consistent model version
• —Seed Control: Random seed set to 42 for reproducible chunking
• —Decision Logging: Complete audit trail of all coding decisions
• —Validation Pipeline: Automatic quality checks

Quality Assurance

• —Code Validation: Ensures codes exist in codebook
• —Quote Verification: Confirms supporting quotes exist in text
• —Confidence Filtering: Removes low-confidence assignments
• —Consistency Tracking: Uses previous codes to maintain consistency

Chunk Management

• —Contextual Preservation: Maintains Q&A relationships
• —Token Optimization: Intelligent chunking for API limits
• —Speaker Attribution: Clear interviewer vs. interviewee distinction

API Usage & Costs

This app uses the Anthropic Claude API. Costs depend on:

• —Model Selected: Sonnet vs. Haiku
• —Transcript Length: Longer interviews require more API calls
• —Chunk Size: Smaller chunks = more API calls

Estimation: A 60-minute interview (~15,000 words) typically costs $2-5 using Claude Sonnet.

Troubleshooting

Common Issues

"No JSON found in response"

• —Claude sometimes returns malformed JSON
• —App includes retry logic (3 attempts)
• —Check API key and model availability

"Quote not found in segment"

• —Claude may hallucinate quotes
• —Validation flags these for review
• —Consider lowering confidence threshold

"Invalid code name"

• —Claude used a code not in your codebook
• —Review codebook completeness
• —Add missing codes or refine definitions

Performance Optimization

Large Transcripts (>20,000 words)

• —Increase chunk size to 4000-5000 tokens
• —Use Claude Haiku for faster processing
• —Consider pre-processing to remove filler words

Low Coding Accuracy

• —Review and refine code definitions
• —Add more specific key indicators
• —Include coding examples in guidelines
• —Lower confidence threshold to capture more codes

Export Issues

QDPX Import Problems

• —Ensure Atlas.ti version compatibility
• —Check character encoding (UTF-8)
• —Verify quote position calculations

Technical Details

Architecture

Transcript → Parser → Chunks → Claude API → Validator → Results → QDPX

Data Flow

1. 1.Parsing: Speaker identification and segmentation
2. 2.Chunking: Context-preserving token management
3. 3.Prompting: Structured prompts with codebook integration
4. 4.Validation: Multi-layer quality control
5. 5.Export: Atlas.ti compatible format generation

Security

• —API keys stored locally (not transmitted)
• —No transcript data retention
• —Local processing with external API calls only

Citation

If you use this tool in academic research, please cite:

Qualitative Coding with Claude API (2024). 
Systematic interview transcript coding using large language models.
Available at: [Your Hugging Face Space URL]

Support

For issues, feature requests, or questions:

1. 1.Check the troubleshooting section above
2. 2.Review Claude API documentation
3. 3.Open an issue on this Hugging Face space

License

This project is licensed under the MIT License. See LICENSE file for details.

Note: This tool is designed for research purposes. Always review AI-generated codes for accuracy and consistency with your research methodology.