# smoosh: Software Module Outline & Organization Summary Helper
smoosh is a Python tool that helps developers understand and work with code repositories by generating LLM-optimized summaries of software modules, structure, dependencies, and patterns. It creates compressed yet meaningful representations that can be effectively used in LLM prompts for package understanding and troubleshooting.
## Features
- **Repo Snapshot**: Copy code repositories to clipboard as plaintext and paste to your favorite AI tools!
- **Smart Exclusion**: Exclude files in .gitignore, non-text, caches, large data files
- **Flexible Output Formats**: Export summaries in text, JSON, or YAML
- **Command Line Interface**: Easy-to-use CLI for quick analysis
## Installation
```bash
pip install smoosh
```
## Quick Start
Analyze a Python package and generate a summary:
```bash
smoosh /path/to/package
```
Export to specific format:
```bash
smoosh /path/to/package --format json --output summary.json
```
## Configuration (optional)
Create a `smoosh.yaml` in your project root:
```yaml
analysis:
exclude_patterns: ['tests/*', '**/__pycache__/*']
max_depth: 3
focus: ['api', 'structure', 'patterns']
compression:
level: medium # low, medium, high
custom_patterns:
df_ops: "standard pandas operations"
api_call: "external service request/response"
output:
format: json
include_schema: true
max_tokens: 1000
```
## Example Output
```
╭───────────────────────────────────────────────────────────────╮
│ 🐍 smoosh v0.1.2 - Making Python packages digestible! │
╰───────────────────────────────────────────────────────────────╯
⠋ Analyzing repository...INFO: Processing directory at code/smoosh
⠋ Analyzing repository...
⠋ Generating summary...
✨ Output copied to clipboard!
Analysis Results
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┓
┃ Metric ┃ Value ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━┩
│ Repository Size │ 0.06MB │
│ Total Files │ 36 │
│ Python Files │ 17 │
│ Original Lines │ 2436 │
│ Composed Lines │ 2520 │
│ Original Characters │ 62187 │
│ Composed Characters │ 63366 │
│ Lines Ratio │ 1.03x │
│ Characters Ratio │ 1.02x │
└─────────────────────┴────────┘
⠹ Analyzing repository...
⠹ Generating summary...
```
**Clipboard output**
```
Repository: smoosh
Mode: cat
Files: 36 (17 Python)
Total Size: 0.06MB
Repository Structure:
smoosh/
├── .github/
│ └── workflows/
│ ├── ci.yml
│ ├── publish.yml
│ └── release-candidate.yml
├── src/
│ └── smoosh/
│ ├── analyzer/
│ │ ├── __init__.py
│ │ ├── repository.py
│ │ └── tree.py
│ ├── composer/
│ │ ├── __init__.py
│ │ ├── concatenator.py
│ │ └── formatter.py
│ ├── utils/
│ │ ├── __init__.py
│ │ ├── config.py
│ │ ├── file_utils.py
│ │ ├── logger.py
│ │ └── path_resolver.py
│ ├── __init__.py
│ ├── custom_types.py
│ └── version.py
├── tests/
│ ├── utils/
│ │ └── generate_sample.py
│ ├── __init__.py
│ └── test_cli.py
├── .flake8
├── .gitignore
├── .pre-commit-config.yaml
├── DEVELOPMENT.md
├── LICENSE
├── pyproject.toml
└── README.md
### File: .flake8 ###
[flake8]
max-line-length = 100
exclude =
.git,
__pycache__,
build,
dist
```
## Development
1. Clone the repository:
```bash
git clone https://github.com/yourusername/smoosh.git
cd smoosh
```
2. Create a virtual environment:
```bash
python -m venv venv
source venv/bin/activate # or `venv\Scripts\activate` on Windows
```
3. Install development dependencies:
```bash
pip install -e ".[dev]"
```
4. Run tests:
```bash
pytest
```
## Contributing
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Roadmap
Future developments may include:
- Smart Compression: Generate compact package representations while preserving essential information
- LLM-Optimized Output: Create summaries specifically formatted for effective use with Language Models
- Error pattern detection
- IDE integration
- Documentation generation
- Intelligent type abbreviation
- Pattern reference system
- Call chain compression
- Reference deduplication
## Support
For questions and support, please open an issue in the GitHub repository.
Raw data
{
"_id": null,
"home_page": null,
"name": "smoosh",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "analysis, ast, llm, python, summary",
"author": "Joshua T. McNamara",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/71/b2/17f756f7083900d22be262a9ab6a12a67ad9ea99b227ddf16555fc0c26b6/smoosh-0.1.3.tar.gz",
"platform": null,
"description": "# smoosh: Software Module Outline & Organization Summary Helper\n\nsmoosh is a Python tool that helps developers understand and work with code repositories by generating LLM-optimized summaries of software modules, structure, dependencies, and patterns. It creates compressed yet meaningful representations that can be effectively used in LLM prompts for package understanding and troubleshooting.\n\n## Features\n\n- **Repo Snapshot**: Copy code repositories to clipboard as plaintext and paste to your favorite AI tools!\n- **Smart Exclusion**: Exclude files in .gitignore, non-text, caches, large data files\n- **Flexible Output Formats**: Export summaries in text, JSON, or YAML\n- **Command Line Interface**: Easy-to-use CLI for quick analysis\n\n## Installation\n\n```bash\npip install smoosh\n```\n\n## Quick Start\n\nAnalyze a Python package and generate a summary:\n\n```bash\nsmoosh /path/to/package\n```\n\nExport to specific format:\n\n```bash\nsmoosh /path/to/package --format json --output summary.json\n```\n\n## Configuration (optional)\n\nCreate a `smoosh.yaml` in your project root:\n\n```yaml\nanalysis:\n exclude_patterns: ['tests/*', '**/__pycache__/*']\n max_depth: 3\n focus: ['api', 'structure', 'patterns']\n\ncompression:\n level: medium # low, medium, high\n custom_patterns:\n df_ops: \"standard pandas operations\"\n api_call: \"external service request/response\"\n\noutput:\n format: json\n include_schema: true\n max_tokens: 1000\n```\n\n## Example Output\n\n```\n\u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 \ud83d\udc0d smoosh v0.1.2 - Making Python packages digestible! \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n\u280b Analyzing repository...INFO: Processing directory at code/smoosh\n\u280b Analyzing repository...\n\u280b Generating summary...\n\u2728 Output copied to clipboard!\n Analysis Results\n\u250f\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2513\n\u2503 Metric \u2503 Value \u2503\n\u2521\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2529\n\u2502 Repository Size \u2502 0.06MB \u2502\n\u2502 Total Files \u2502 36 \u2502\n\u2502 Python Files \u2502 17 \u2502\n\u2502 Original Lines \u2502 2436 \u2502\n\u2502 Composed Lines \u2502 2520 \u2502\n\u2502 Original Characters \u2502 62187 \u2502\n\u2502 Composed Characters \u2502 63366 \u2502\n\u2502 Lines Ratio \u2502 1.03x \u2502\n\u2502 Characters Ratio \u2502 1.02x \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\u2839 Analyzing repository...\n\u2839 Generating summary...\n```\n**Clipboard output**\n```\nRepository: smoosh\nMode: cat\nFiles: 36 (17 Python)\nTotal Size: 0.06MB\n\nRepository Structure:\nsmoosh/\n \u251c\u2500\u2500 .github/\n \u2502 \u2514\u2500\u2500 workflows/\n \u2502 \u251c\u2500\u2500 ci.yml\n \u2502 \u251c\u2500\u2500 publish.yml\n \u2502 \u2514\u2500\u2500 release-candidate.yml\n \u251c\u2500\u2500 src/\n \u2502 \u2514\u2500\u2500 smoosh/\n \u2502 \u251c\u2500\u2500 analyzer/\n \u2502 \u2502 \u251c\u2500\u2500 __init__.py\n \u2502 \u2502 \u251c\u2500\u2500 repository.py\n \u2502 \u2502 \u2514\u2500\u2500 tree.py\n \u2502 \u251c\u2500\u2500 composer/\n \u2502 \u2502 \u251c\u2500\u2500 __init__.py\n \u2502 \u2502 \u251c\u2500\u2500 concatenator.py\n \u2502 \u2502 \u2514\u2500\u2500 formatter.py\n \u2502 \u251c\u2500\u2500 utils/\n \u2502 \u2502 \u251c\u2500\u2500 __init__.py\n \u2502 \u2502 \u251c\u2500\u2500 config.py\n \u2502 \u2502 \u251c\u2500\u2500 file_utils.py\n \u2502 \u2502 \u251c\u2500\u2500 logger.py\n \u2502 \u2502 \u2514\u2500\u2500 path_resolver.py\n \u2502 \u251c\u2500\u2500 __init__.py\n \u2502 \u251c\u2500\u2500 custom_types.py\n \u2502 \u2514\u2500\u2500 version.py\n \u251c\u2500\u2500 tests/\n \u2502 \u251c\u2500\u2500 utils/\n \u2502 \u2502 \u2514\u2500\u2500 generate_sample.py\n \u2502 \u251c\u2500\u2500 __init__.py\n \u2502 \u2514\u2500\u2500 test_cli.py\n \u251c\u2500\u2500 .flake8\n \u251c\u2500\u2500 .gitignore\n \u251c\u2500\u2500 .pre-commit-config.yaml\n \u251c\u2500\u2500 DEVELOPMENT.md\n \u251c\u2500\u2500 LICENSE\n \u251c\u2500\u2500 pyproject.toml\n \u2514\u2500\u2500 README.md\n\n\n\n### File: .flake8 ###\n[flake8]\nmax-line-length = 100\nexclude =\n .git,\n __pycache__,\n build,\n dist\n```\n\n## Development\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/yourusername/smoosh.git\ncd smoosh\n```\n\n2. Create a virtual environment:\n```bash\npython -m venv venv\nsource venv/bin/activate # or `venv\\Scripts\\activate` on Windows\n```\n\n3. Install development dependencies:\n```bash\npip install -e \".[dev]\"\n```\n\n4. Run tests:\n```bash\npytest\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Roadmap\n\nFuture developments may include:\n- Smart Compression: Generate compact package representations while preserving essential information\n- LLM-Optimized Output: Create summaries specifically formatted for effective use with Language Models\n- Error pattern detection\n- IDE integration\n- Documentation generation\n- Intelligent type abbreviation\n- Pattern reference system\n- Call chain compression\n- Reference deduplication\n\n## Support\n\nFor questions and support, please open an issue in the GitHub repository.\n",
"bugtrack_url": null,
"license": null,
"summary": "Software Module Outline & Organization Summary Helper",
"version": "0.1.3",
"project_urls": {
"Bug Tracker": "https://github.com/j-mcnamara/smoosh/issues",
"Documentation": "https://github.com/j-mcnamara/smoosh#readme",
"Homepage": "https://github.com/j-mcnamara/smoosh"
},
"split_keywords": [
"analysis",
" ast",
" llm",
" python",
" summary"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b9c4833535a59065edda8ce8833a740e95667b567819cf948e668175000b3a74",
"md5": "c651ed580d8406c9e1a49d84ff09e8f3",
"sha256": "427e9e65d752c1a5e743fed0f55890ec53bb46ffe7bf65f33ace46a873474bc7"
},
"downloads": -1,
"filename": "smoosh-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c651ed580d8406c9e1a49d84ff09e8f3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 20163,
"upload_time": "2025-01-23T14:56:27",
"upload_time_iso_8601": "2025-01-23T14:56:27.980868Z",
"url": "https://files.pythonhosted.org/packages/b9/c4/833535a59065edda8ce8833a740e95667b567819cf948e668175000b3a74/smoosh-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "71b217f756f7083900d22be262a9ab6a12a67ad9ea99b227ddf16555fc0c26b6",
"md5": "dc1033b90d3b960446ff56f241321895",
"sha256": "5c493b23f9fa15cc3798c6d393178dfbb4fffd39c1568d48fe9fecfe250ff51d"
},
"downloads": -1,
"filename": "smoosh-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "dc1033b90d3b960446ff56f241321895",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 21813,
"upload_time": "2025-01-23T14:56:29",
"upload_time_iso_8601": "2025-01-23T14:56:29.522564Z",
"url": "https://files.pythonhosted.org/packages/71/b2/17f756f7083900d22be262a9ab6a12a67ad9ea99b227ddf16555fc0c26b6/smoosh-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-23 14:56:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "j-mcnamara",
"github_project": "smoosh",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "smoosh"
}
JSON
