# 🔍 ChatScope
[](https://www.python.org/downloads/)
[](https://github.com/22wojciech/chatscope/blob/main/LICENSE)
[](https://badge.fury.io/py/chatscope)
**Discover the scope of your conversations**
A powerful Python library for analyzing and categorizing ChatGPT conversation exports using OpenAI's API. This tool helps you understand your ChatGPT usage patterns by automatically categorizing your conversations into topics like Programming, AI, Psychology, Philosophy, and more.
## Features
- 📊 **Automatic Categorization**: Uses GPT-4 to intelligently categorize your conversations
- 📈 **Visual Analytics**: Generates beautiful bar charts showing conversation distribution
- 🔒 **Secure**: API keys loaded from environment variables
- ⚡ **Rate Limiting**: Built-in rate limiting to respect OpenAI API limits
- 🔄 **Batch Processing**: Efficiently processes large numbers of conversations
- 💾 **Export Results**: Saves detailed results in JSON format
- 🎨 **Customizable**: Custom categories and visualization options
- 🖥️ **CLI Support**: Command-line interface for easy automation
## Installation
### From PyPI (Recommended)
```bash
pip install chatscope
```
### With plotting support
```bash
pip install chatscope[plotting]
```
### Development Installation
```bash
git clone https://github.com/22wojciech/chatscope.git
cd chatscope
pip install -e .[dev]
```
## Quick Start
### 1. Get Your ChatGPT Data
1. Go to [ChatGPT Settings](https://chat.openai.com/)
2. Navigate to "Data controls" → "Export data"
3. Download your data and extract `conversations.json`
### 2. Set Up OpenAI API Key
Create a `.env` file in your project directory:
```env
OPENAI_API_KEY=your_openai_api_key_here
```
Or set it as an environment variable:
```bash
export OPENAI_API_KEY="your_openai_api_key_here"
```
### 3. Run Analysis
#### Using Python API
```python
from chatscope import ChatGPTAnalyzer
# Initialize analyzer
analyzer = ChatGPTAnalyzer()
# Run analysis
results = analyzer.analyze('conversations.json')
# Print results
print(f"Total conversations: {results['total_conversations']}")
for category, count in results['counts'].items():
if count > 0:
print(f"{category}: {count}")
```
#### Using Command Line
```bash
# Basic usage
chatscope conversations.json
# Custom output paths
chatscope conversations.json -o my_chart.png -r my_results.json
# Don't show the plot
chatscope conversations.json --no-show
```
## Advanced Usage
### Custom Categories
```python
from chatscope import ChatGPTAnalyzer
custom_categories = [
"Work",
"Personal",
"Learning",
"Creative",
"Technical",
"Other"
]
analyzer = ChatGPTAnalyzer(categories=custom_categories)
results = analyzer.analyze('conversations.json')
```
### Rate Limiting Configuration
```python
analyzer = ChatGPTAnalyzer(
batch_size=10, # Process 10 titles per request
delay_between_requests=2.0, # Wait 2 seconds between requests
max_tokens_per_request=3000 # Limit tokens per request
)
```
### Programmatic Chart Generation
```python
analyzer = ChatGPTAnalyzer()
results = analyzer.analyze(
'conversations.json',
output_chart='custom_chart.png',
show_plot=False # Don't display, just save
)
```
## Command Line Interface
The package includes a comprehensive CLI:
```bash
chatscope --help
```
### CLI Examples
```bash
# Basic analysis
chatscope conversations.json
# Custom API key and batch size
chatscope --api-key sk-... --batch-size 15 conversations.json
# Custom categories
chatscope --categories "Work" "Personal" "Learning" conversations.json
# Verbose output
chatscope -v conversations.json
# Quiet mode (only errors)
chatscope -q conversations.json
# Custom figure size
chatscope --figsize 16 10 conversations.json
```
## Data Format
Your `conversations.json` should follow this structure:
```json
[
{
"title": "Python Data Analysis Tutorial",
"create_time": 1699123456.789,
"update_time": 1699123456.789
},
{
"title": "Machine Learning Basics",
"create_time": 1699123456.789,
"update_time": 1699123456.789
}
]
```
## Default Categories
The analyzer uses these categories by default:
- **Programming** - Code, software development, debugging
- **Artificial Intelligence** - AI, ML, data science topics
- **Psychology / Personal Development** - Mental health, self-improvement
- **Philosophy** - Philosophical discussions and questions
- **Astrology / Esoteric** - Spiritual and mystical topics
- **Work / Career** - Professional and career-related conversations
- **Health** - Medical, fitness, and wellness topics
- **Education** - Learning, academic subjects
- **Other** - Everything else
## Output Files
The analyzer generates several output files:
### 1. Chart (`conversation_categories.png`)
A bar chart showing the distribution of conversations across categories.
### 2. Detailed Results (`categorization_results.json`)
```json
{
"timestamp": "2024-01-15T10:30:00",
"total_conversations": 150,
"categories": {
"Programming": ["Python Tutorial", "Debug Help"],
"AI": ["ChatGPT Tips", "ML Basics"]
},
"counts": {
"Programming": 45,
"AI": 32,
"Other": 73
}
}
```
## Error Handling
The library includes comprehensive error handling:
```python
from chatscope import ChatGPTAnalyzer
from chatscope.exceptions import ChatGPTAnalyzerError
try:
analyzer = ChatGPTAnalyzer()
results = analyzer.analyze('conversations.json')
except APIError as e:
print(f"OpenAI API error: {e}")
except DataError as e:
print(f"Data processing error: {e}")
except Exception as e:
print(f"Unexpected error: {e}")
```
## Requirements
- Python 3.8+
- OpenAI API key
- Required packages (automatically installed):
- `openai>=0.28.0`
- `python-dotenv>=0.19.0`
- `requests>=2.25.0`
- Optional packages:
- `matplotlib>=3.5.0` (for plotting)
## API Costs
The tool uses OpenAI's GPT-4 API. Costs depend on:
- Number of conversation titles
- Batch size (larger batches = fewer API calls)
- Title length and complexity
Typical costs:
- ~100 conversations: $0.10-0.50
- ~1000 conversations: $1.00-5.00
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
### Development Setup
```bash
git clone https://github.com/22wojciech/chatscope.git
cd chatscope
pip install -e .[dev]
```
### Running Tests
```bash
pytest
```
### Code Formatting
```bash
black chatscope/
flake8 chatscope/
```
## License
This project is licensed under the Custom Non-Commercial License (CNCL) v1.0 - see the [LICENSE](https://github.com/22wojciech/chatscope/blob/main/LICENSE) file for details.
**⚠️ Important:** This software is free for personal, academic, and research use only. Commercial use requires a separate license. Contact plus4822@icloud.com for commercial licensing.
## Changelog
### v1.0.0
- Initial release
- Basic conversation categorization
- CLI interface
- Plotting support
- Rate limiting
- Comprehensive error handling
## Support
If you encounter any issues or have questions:
1. Check the [Issues](https://github.com/22wojciech/chatscope/issues) page
2. Create a new issue with detailed information
3. Include your Python version, OS, and error messages
## Acknowledgments
- OpenAI for providing the GPT-4 API
- The Python community for excellent libraries
- Contributors and users who provide feedback
---
**Made with ❤️ for the ChatGPT community**
Raw data
{
"_id": null,
"home_page": null,
"name": "chatscope",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "chatgpt, openai, conversation, analysis, categorization, nlp",
"author": null,
"author_email": "22wojciech <plus4822@icloud.com>",
"download_url": "https://files.pythonhosted.org/packages/5a/b6/4c4a645d6dcc6263a5a1504c72723deac650bb14b0e01121b9fe2da33894/chatscope-1.0.2.tar.gz",
"platform": null,
"description": "# \ud83d\udd0d ChatScope\n\n[](https://www.python.org/downloads/)\n[](https://github.com/22wojciech/chatscope/blob/main/LICENSE)\n[](https://badge.fury.io/py/chatscope)\n\n**Discover the scope of your conversations**\n\nA powerful Python library for analyzing and categorizing ChatGPT conversation exports using OpenAI's API. This tool helps you understand your ChatGPT usage patterns by automatically categorizing your conversations into topics like Programming, AI, Psychology, Philosophy, and more.\n\n## Features\n\n- \ud83d\udcca **Automatic Categorization**: Uses GPT-4 to intelligently categorize your conversations\n- \ud83d\udcc8 **Visual Analytics**: Generates beautiful bar charts showing conversation distribution\n- \ud83d\udd12 **Secure**: API keys loaded from environment variables\n- \u26a1 **Rate Limiting**: Built-in rate limiting to respect OpenAI API limits\n- \ud83d\udd04 **Batch Processing**: Efficiently processes large numbers of conversations\n- \ud83d\udcbe **Export Results**: Saves detailed results in JSON format\n- \ud83c\udfa8 **Customizable**: Custom categories and visualization options\n- \ud83d\udda5\ufe0f **CLI Support**: Command-line interface for easy automation\n\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\npip install chatscope\n```\n\n### With plotting support\n\n```bash\npip install chatscope[plotting]\n```\n\n### Development Installation\n\n```bash\ngit clone https://github.com/22wojciech/chatscope.git\ncd chatscope\npip install -e .[dev]\n```\n\n## Quick Start\n\n### 1. Get Your ChatGPT Data\n\n1. Go to [ChatGPT Settings](https://chat.openai.com/)\n2. Navigate to \"Data controls\" \u2192 \"Export data\"\n3. Download your data and extract `conversations.json`\n\n### 2. Set Up OpenAI API Key\n\nCreate a `.env` file in your project directory:\n\n```env\nOPENAI_API_KEY=your_openai_api_key_here\n```\n\nOr set it as an environment variable:\n\n```bash\nexport OPENAI_API_KEY=\"your_openai_api_key_here\"\n```\n\n### 3. Run Analysis\n\n#### Using Python API\n\n```python\nfrom chatscope import ChatGPTAnalyzer\n\n# Initialize analyzer\nanalyzer = ChatGPTAnalyzer()\n\n# Run analysis\nresults = analyzer.analyze('conversations.json')\n\n# Print results\nprint(f\"Total conversations: {results['total_conversations']}\")\nfor category, count in results['counts'].items():\n if count > 0:\n print(f\"{category}: {count}\")\n```\n\n#### Using Command Line\n\n```bash\n# Basic usage\nchatscope conversations.json\n\n# Custom output paths\nchatscope conversations.json -o my_chart.png -r my_results.json\n\n# Don't show the plot\nchatscope conversations.json --no-show\n```\n\n## Advanced Usage\n\n### Custom Categories\n\n```python\nfrom chatscope import ChatGPTAnalyzer\n\ncustom_categories = [\n \"Work\",\n \"Personal\",\n \"Learning\",\n \"Creative\",\n \"Technical\",\n \"Other\"\n]\n\nanalyzer = ChatGPTAnalyzer(categories=custom_categories)\nresults = analyzer.analyze('conversations.json')\n```\n\n### Rate Limiting Configuration\n\n```python\nanalyzer = ChatGPTAnalyzer(\n batch_size=10, # Process 10 titles per request\n delay_between_requests=2.0, # Wait 2 seconds between requests\n max_tokens_per_request=3000 # Limit tokens per request\n)\n```\n\n### Programmatic Chart Generation\n\n```python\nanalyzer = ChatGPTAnalyzer()\nresults = analyzer.analyze(\n 'conversations.json',\n output_chart='custom_chart.png',\n show_plot=False # Don't display, just save\n)\n```\n\n## Command Line Interface\n\nThe package includes a comprehensive CLI:\n\n```bash\nchatscope --help\n```\n\n### CLI Examples\n\n```bash\n# Basic analysis\nchatscope conversations.json\n\n# Custom API key and batch size\nchatscope --api-key sk-... --batch-size 15 conversations.json\n\n# Custom categories\nchatscope --categories \"Work\" \"Personal\" \"Learning\" conversations.json\n\n# Verbose output\nchatscope -v conversations.json\n\n# Quiet mode (only errors)\nchatscope -q conversations.json\n\n# Custom figure size\nchatscope --figsize 16 10 conversations.json\n```\n\n## Data Format\n\nYour `conversations.json` should follow this structure:\n\n```json\n[\n {\n \"title\": \"Python Data Analysis Tutorial\",\n \"create_time\": 1699123456.789,\n \"update_time\": 1699123456.789\n },\n {\n \"title\": \"Machine Learning Basics\",\n \"create_time\": 1699123456.789,\n \"update_time\": 1699123456.789\n }\n]\n```\n\n## Default Categories\n\nThe analyzer uses these categories by default:\n\n- **Programming** - Code, software development, debugging\n- **Artificial Intelligence** - AI, ML, data science topics\n- **Psychology / Personal Development** - Mental health, self-improvement\n- **Philosophy** - Philosophical discussions and questions\n- **Astrology / Esoteric** - Spiritual and mystical topics\n- **Work / Career** - Professional and career-related conversations\n- **Health** - Medical, fitness, and wellness topics\n- **Education** - Learning, academic subjects\n- **Other** - Everything else\n\n## Output Files\n\nThe analyzer generates several output files:\n\n### 1. Chart (`conversation_categories.png`)\nA bar chart showing the distribution of conversations across categories.\n\n### 2. Detailed Results (`categorization_results.json`)\n```json\n{\n \"timestamp\": \"2024-01-15T10:30:00\",\n \"total_conversations\": 150,\n \"categories\": {\n \"Programming\": [\"Python Tutorial\", \"Debug Help\"],\n \"AI\": [\"ChatGPT Tips\", \"ML Basics\"]\n },\n \"counts\": {\n \"Programming\": 45,\n \"AI\": 32,\n \"Other\": 73\n }\n}\n```\n\n## Error Handling\n\nThe library includes comprehensive error handling:\n\n```python\nfrom chatscope import ChatGPTAnalyzer\nfrom chatscope.exceptions import ChatGPTAnalyzerError\n\ntry:\n analyzer = ChatGPTAnalyzer()\n results = analyzer.analyze('conversations.json')\nexcept APIError as e:\n print(f\"OpenAI API error: {e}\")\nexcept DataError as e:\n print(f\"Data processing error: {e}\")\nexcept Exception as e:\n print(f\"Unexpected error: {e}\")\n```\n\n## Requirements\n\n- Python 3.8+\n- OpenAI API key\n- Required packages (automatically installed):\n - `openai>=0.28.0`\n - `python-dotenv>=0.19.0`\n - `requests>=2.25.0`\n- Optional packages:\n - `matplotlib>=3.5.0` (for plotting)\n\n## API Costs\n\nThe tool uses OpenAI's GPT-4 API. Costs depend on:\n- Number of conversation titles\n- Batch size (larger batches = fewer API calls)\n- Title length and complexity\n\nTypical costs:\n- ~100 conversations: $0.10-0.50\n- ~1000 conversations: $1.00-5.00\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n### Development Setup\n\n```bash\ngit clone https://github.com/22wojciech/chatscope.git\ncd chatscope\npip install -e .[dev]\n```\n\n### Running Tests\n\n```bash\npytest\n```\n\n### Code Formatting\n\n```bash\nblack chatscope/\nflake8 chatscope/\n```\n\n## License\n\nThis project is licensed under the Custom Non-Commercial License (CNCL) v1.0 - see the [LICENSE](https://github.com/22wojciech/chatscope/blob/main/LICENSE) file for details.\n\n**\u26a0\ufe0f Important:** This software is free for personal, academic, and research use only. Commercial use requires a separate license. Contact plus4822@icloud.com for commercial licensing.\n\n## Changelog\n\n### v1.0.0\n- Initial release\n- Basic conversation categorization\n- CLI interface\n- Plotting support\n- Rate limiting\n- Comprehensive error handling\n\n## Support\n\nIf you encounter any issues or have questions:\n\n1. Check the [Issues](https://github.com/22wojciech/chatscope/issues) page\n2. Create a new issue with detailed information\n3. Include your Python version, OS, and error messages\n\n## Acknowledgments\n\n- OpenAI for providing the GPT-4 API\n- The Python community for excellent libraries\n- Contributors and users who provide feedback\n\n---\n\n**Made with \u2764\ufe0f for the ChatGPT community**\n",
"bugtrack_url": null,
"license": "Custom Non-Commercial License (CNCL) v1.0",
"summary": "Analyze and categorize ChatGPT conversation exports using OpenAI API",
"version": "1.0.2",
"project_urls": {
"Bug Reports": "https://github.com/22wojciech/chatscope/issues",
"Documentation": "https://github.com/22wojciech/chatscope#readme",
"Homepage": "https://github.com/22wojciech/chatscope",
"Source": "https://github.com/22wojciech/chatscope"
},
"split_keywords": [
"chatgpt",
" openai",
" conversation",
" analysis",
" categorization",
" nlp"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "31306ad827ad34d6cc99ed97de81265b6f90dc81d4706e52854acda239503da6",
"md5": "f01610cd04d7ede699fb4239305ebebf",
"sha256": "861b759341da2762f7df87b3581917a5b48ffa262bc8f31994fc00cbe766ad10"
},
"downloads": -1,
"filename": "chatscope-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f01610cd04d7ede699fb4239305ebebf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 12388,
"upload_time": "2025-07-11T20:43:48",
"upload_time_iso_8601": "2025-07-11T20:43:48.891080Z",
"url": "https://files.pythonhosted.org/packages/31/30/6ad827ad34d6cc99ed97de81265b6f90dc81d4706e52854acda239503da6/chatscope-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5ab64c4a645d6dcc6263a5a1504c72723deac650bb14b0e01121b9fe2da33894",
"md5": "6bfdcad2a10e4bf31b50bdcedd4b3f5e",
"sha256": "3bb70660f4b599a7a439c86b74f424148a95f5d757699c4538ae512cfc090492"
},
"downloads": -1,
"filename": "chatscope-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "6bfdcad2a10e4bf31b50bdcedd4b3f5e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 17377,
"upload_time": "2025-07-11T20:43:49",
"upload_time_iso_8601": "2025-07-11T20:43:49.994288Z",
"url": "https://files.pythonhosted.org/packages/5a/b6/4c4a645d6dcc6263a5a1504c72723deac650bb14b0e01121b9fe2da33894/chatscope-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-11 20:43:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "22wojciech",
"github_project": "chatscope",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "openai",
"specs": [
[
"<",
"1.0.0"
],
[
">=",
"0.28.0"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"0.19.0"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.25.0"
]
]
},
{
"name": "matplotlib",
"specs": [
[
">=",
"3.5.0"
]
]
}
],
"lcname": "chatscope"
}
JSON
