{"id":40543558,"url":"https://github.com/leggetter/discourse-forum-analyzer","last_synced_at":"2026-01-20T23:16:28.420Z","repository":{"id":317870192,"uuid":"1069170642","full_name":"leggetter/discourse-forum-analyzer","owner":"leggetter","description":"A Python CLI tool that collects and analyzes Discourse forum discussions using Claude AI to identify common problems, categorize issues by severity, and provide natural language querying of forum insights.","archived":false,"fork":false,"pushed_at":"2025-10-07T15:00:35.000Z","size":206,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-21T18:51:29.903Z","etag":null,"topics":["anthropic-claude","claude-ai","cli","discource","llm-analysis","sqlite"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/leggetter.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-03T14:08:04.000Z","updated_at":"2025-10-07T15:00:40.000Z","dependencies_parsed_at":"2025-10-03T16:17:04.641Z","dependency_job_id":"12c237f6-4382-45a3-8f70-f93a6443c20d","html_url":"https://github.com/leggetter/discourse-forum-analyzer","commit_stats":null,"previous_names":["leggetter/discourse-forum-analyzer"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/leggetter/discourse-forum-analyzer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leggetter%2Fdiscourse-forum-analyzer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leggetter%2Fdiscourse-forum-analyzer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leggetter%2Fdiscourse-forum-analyzer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leggetter%2Fdiscourse-forum-analyzer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leggetter","download_url":"https://codeload.github.com/leggetter/discourse-forum-analyzer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leggetter%2Fdiscourse-forum-analyzer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28618797,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T22:24:05.405Z","status":"ssl_error","status_checked_at":"2026-01-20T22:20:31.342Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anthropic-claude","claude-ai","cli","discource","llm-analysis","sqlite"],"created_at":"2026-01-20T23:16:27.935Z","updated_at":"2026-01-20T23:16:28.412Z","avatar_url":"https://github.com/leggetter.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Discourse Forum Analyzer\n\nA Python tool for collecting and analyzing discussions from Discourse-based forums using LLM-powered analysis.\n\n## Overview\n\nThis tool automates the collection of forum data from Discourse forums (which provide JSON representations of pages) and uses Claude AI to analyze discussions, identify common problems, and extract insights. While initially built to analyze Shopify's webhook forum, it works with any publicly accessible Discourse installation.\n\n**New to this tool?** It's recommended to read the [Glossary](#glossary) to understand key terminology.\n\n## Features\n\n### Data Collection\n- Automated scraping via Discourse JSON endpoints\n- Rate-limited HTTP client with retry logic\n- Checkpoint-based recovery for interrupted operations\n- Incremental updates (collect only new content)\n- SQLite storage with SQLAlchemy ORM\n\n### LLM Analysis\n- Problem extraction from discussion threads\n- Automatic categorization by topic type\n- Severity assessment (critical, high, medium, low)\n- Theme identification across multiple discussions\n- Natural language query interface\n\n### Reporting\n- Markdown reports with statistics\n- Problem theme grouping\n- JSON and CSV export options\n\n## Requirements\n\n- Python 3.10 or higher\n- Anthropic API key (for LLM analysis features)\n\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\npip install forum-analyzer\n```\n\n### From Source (Development)\n\n```bash\ngit clone https://github.com/leggetter/discourse-forum-analyzer.git\ncd discourse-forum-analyzer\n\npython -m venv .venv\nsource .venv/bin/activate  # Windows: .venv\\Scripts\\activate\n\npip install -e .\n```\n\n## Quick Start\n\n### 1. Initialize a New Project\n\nCreate a new directory for your analysis project and initialize it:\n\n```bash\nmkdir my-forum-analysis\ncd my-forum-analysis\nforum-analyzer init\n```\n\nThe `init` command will interactively prompt you for:\n- Discourse forum URL\n- Category path (e.g., 't' or 'c')\n- Category ID (with helpful hints; slug fetched automatically)\n- Anthropic API key (optional, can be added later)\n\nThis creates a project structure:\n```\nmy-forum-analysis/\n├── config.yaml          # Your configuration\n├── forum.db            # SQLite database (created on first collect)\n├── checkpoints/        # Recovery checkpoints\n├── exports/            # Analysis reports\n└── logs/               # Application logs\n```\n\n### 2. Recommended Workflow\n\nThe recommended workflow ensures the most accurate and relevant analysis by first discovering themes from your specific data.\n\n```bash\n# 1. Collect forum data (initializes database automatically)\nforum-analyzer collect\n\n# 2. Discover natural categories from the data\nforum-analyzer themes discover --min-topics 3\n\n# 3. Analyze all topics using the discovered categories\nforum-analyzer llm-analyze\n\n# 4. Ask questions about your analysis\nforum-analyzer ask \"What are the main authentication issues?\"\n```\n\n## Working with Multiple Projects\n\nYou can work with multiple forum analysis projects by using the `--dir` flag:\n\n```bash\n# Initialize a new project in a specific directory\nmkdir shopify-webhooks\nforum-analyzer --dir shopify-webhooks init\n\n# Collect data for that project\nforum-analyzer --dir shopify-webhooks collect\n\n# Or use environment variable\nexport FORUM_ANALYZER_DIR=./shopify-webhooks\nforum-analyzer collect\n```\n\n## Usage\n\n### All Commands\n\nA full list of commands and their options are available below.\n\n#### Project Initialization\n```bash\n# Initialize a new project in the current directory\nforum-analyzer init\n\n# Initialize in a specific directory\nforum-analyzer --dir ./my-project init\n\n# Overwrite existing configuration\nforum-analyzer init --force\n```\n\n#### Data Collection\n```bash\n# Collect from the category in your config\nforum-analyzer collect\n\n# Collect from a specific category\nforum-analyzer collect --category-id 25\n\n# Collect with a page limit (for testing)\nforum-analyzer collect --page-limit 2\n\n# Collect from a different project directory\nforum-analyzer --dir ./my-project collect\n```\n\n#### Incremental Updates\n```bash\n# Fetch only new/updated content\nforum-analyzer update\n```\n\n#### Status\n```bash\n# View collection status and statistics\nforum-analyzer status\n```\n\n#### Theme Management\n```bash\n# Discover common themes (minimum 3 topics per theme)\nforum-analyzer themes discover\n\n# Analyze more topics for better pattern discovery\nforum-analyzer themes discover --context-limit 100\n\n# List themes already discovered\nforum-analyzer themes list\n\n# Delete all themes (prompts for confirmation)\nforum-analyzer themes clean\n```\n\n#### Topic Analysis\n```bash\n# Analyze all unanalyzed topics\nforum-analyzer llm-analyze\n\n# Re-analyze topics that have already been analyzed\nforum-analyzer llm-analyze --force\n\n# Analyze a specific topic by its ID\nforum-analyzer llm-analyze --topic-id 66\n```\n\n#### Querying\n```bash\n# Ask questions about the analyzed data\nforum-analyzer ask \"What are the most common authentication issues?\"\n```\n\n#### Maintenance\n```bash\n# Clear all collection checkpoints\nforum-analyzer clear-checkpoints\n```\n\n## Technical Details\n\n### Architecture\n\n```\n┌─────────────────────┐\n│  Discourse Forum    │\n│  (JSON endpoints)   │\n└──────────┬──────────┘\n           │\n           ▼\n┌─────────────────────┐\n│   Rate-Limited      │\n│   HTTP Client       │\n└──────────┬──────────┘\n           │\n           ▼\n┌─────────────────────┐\n│   Checkpoint        │\n│   Manager           │\n└──────────┬──────────┘\n           │\n           ▼\n┌─────────────────────┐\n│   SQLite Database   │\n│   (SQLAlchemy)      │\n└──────────┬──────────┘\n           │\n           ▼\n┌─────────────────────┐     ┌──────────────┐\n│   LLM Analyzer      │────▶│  Claude API  │\n└──────────┬──────────┘     └──────────────┘\n           │\n           ▼\n┌─────────────────────┐\n│  Reports \u0026 Themes   │\n└─────────────────────┘\n```\n\n### Technology Stack\n- **Language**: Python 3.10+\n- **Database**: SQLite with SQLAlchemy\n- **HTTP**: httpx (async)\n- **LLM**: Claude API (Anthropic)\n- **CLI**: Click\n- **Config**: Pydantic + YAML\n\n### Project Structure\n```\ndiscourse-forum-analyzer/\n├── src/forum_analyzer/\n│   ├── analyzer/              # LLM analysis\n│   ├── collector/             # Data collection\n│   ├── config/\n│   └── cli.py\n├── config/\n│   └── cli.py\n├── examples/\n│   └── shopify-webhooks/\n└── tests/\n```\n\n### Database Schema\nThe schema is managed by SQLAlchemy models and is split into three categories:\n\n- **Forum Data Tables**: `categories`, `topics`, `posts`, `users`\n- **Analysis Tables**: `llm_analysis`, `problem_themes`\n- **Operational Tables**: `checkpoints`, `fetch_history`\n\nThe schema auto-migrates when using LLM analysis features.\n\n## Example Application: Shopify Developer Forum\n\nThis tool was demonstrated by analyzing Shopify's webhook discussions.\n\n- **Topics**: 271\n- **Posts**: 1,201\n- **Users**: 324\n- **Date Range**: September 2024 - October 2025\n\n**Example analysis results:**\n- 15 distinct problem themes identified\n- 18 critical issues found\n- Top issue: Configuration challenges (25.1% of topics)\n\nSee the complete example analysis: [examples/shopify-webhooks/LLM_ANALYSIS_REPORT.md](examples/shopify-webhooks/LLM_ANALYSIS_REPORT.md)\n\n## Development\n\n### Running Tests\n```bash\npytest\n```\n\n### Code Quality\n```bash\nblack src/ tests/\nisort src/ tests/\nflake8 src/ tests/\nmypy src/\n```\n\n## Troubleshooting\n\n**Rate Limiting**\n- Adjust `rate_limit` in config.yaml (default: 1 req/sec).\n\n## Publishing to PyPI\n\nThis section is for maintainers who need to publish new versions of the package to PyPI.\n\n### Prerequisites\n\n1. **PyPI Account**: Create an account at [pypi.org](https://pypi.org)\n2. **API Token**: Generate an API token from your PyPI account settings\n3. **Build Tools**: Install required packages:\n   ```bash\n   pip install build twine\n   ```\n\n### Setup API Token\n\nStore your PyPI API token in `~/.pypirc`:\n\n```ini\n[pypi]\nusername = __token__\npassword = pypi-YOUR-API-TOKEN-HERE\n```\n\n### Build and Publish\n\n1. **Update Version**: Bump the version in [`pyproject.toml`](pyproject.toml:4)\n   ```toml\n   version = \"0.2.0\"  # Update this line\n   ```\n\n2. **Clean Previous Builds**:\n   ```bash\n   rm -rf dist/ build/ *.egg-info\n   ```\n\n3. **Build Distribution**:\n   ```bash\n   python -m build\n   ```\n\n4. **Upload to PyPI**:\n   ```bash\n   twine upload dist/*\n   ```\n\n5. **Verify Upload**:\n   ```bash\n   pip install --upgrade forum-analyzer\n   forum-analyzer --version\n   ```\n\n### Version Bumping Strategy\n\n- **Patch** (0.1.0 → 0.1.1): Bug fixes, documentation updates\n- **Minor** (0.1.0 → 0.2.0): New features, backward-compatible changes\n- **Major** (0.1.0 → 1.0.0): Breaking changes, major redesigns\n\n### Package Information\n\n- **Package Name**: `forum-analyzer`\n- **PyPI URL**: https://pypi.org/project/forum-analyzer/\n- **Repository**: https://github.com/leggetter/discourse-forum-analyzer\n\n**Database Locked**\n- Only one instance can run at a time.\n- Clear stale checkpoints: `forum-analyzer clear-checkpoints`.\n\n**LLM Analysis Errors**\n- Verify your Anthropic API key is valid and has credit.\n- Use the `--limit` flag for testing with smaller datasets.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make changes with tests\n4. Submit a pull request\n\n## License\n\nMIT License - See [LICENSE](LICENSE) file for details.\n\n---\n\n## Appendix: Glossary\n\nUnderstanding the terminology used in this tool:\n\n### Discourse Forum Terms\n\n**Category**  \nA top-level organizational unit in Discourse forums (e.g., \"Webhooks \u0026 Events\").\n\n**Topic**  \nA discussion thread within a category.\n\n**Post**  \nAn individual message within a topic. The first post is the topic starter; subsequent posts are replies.\n\n### Analysis Terms\n\n**Classification**\nThe LLM-assigned type of problem or discussion in a topic (e.g., \"webhook_delivery\", \"authentication\").\n\n**Theme**  \nA higher-level pattern grouping multiple related topics (e.g., \"Webhook Delivery Failures\").\n\n**Severity**  \nThe urgency/impact level assigned to a topic (critical, high, medium, low).\n\n### Workflow Terms\n\n**Collection**  \nThe process of downloading forum data (`forum-analyzer collect`).\n\n**Analysis**  \nThe process of using the LLM to extract insights from topics (`forum-analyzer llm-analyze`).\n\n**Theme Identification**  \nThe process of grouping topics into common patterns (`forum-analyzer themes discover`).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleggetter%2Fdiscourse-forum-analyzer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleggetter%2Fdiscourse-forum-analyzer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleggetter%2Fdiscourse-forum-analyzer/lists"}