| Name | doggo JSON |
| Version |
0.3.0
JSON |
| download |
| home_page | None |
| Summary | Your loyal digital companion who finds files the way you think about them |
| upload_time | 2025-07-14 02:14:21 |
| maintainer | None |
| docs_url | None |
| author | n0lan |
| requires_python | >=3.11 |
| license | MIT |
| keywords |
ai
cli
files
images
search
semantic
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<p align="center">
<img src="./docs/doggo.png" width="400" height="200" style="border-radius: 10px;" alt="Doggo">
</p>
<p align="center">
<em>Doggo 🐕, your loyal digital companion who finds files the way you think about them.</em>
</p>
<p align="center">
<a href="https://github.com/0nsh/doggo/actions/workflows/test.yaml" target="_blank">
<img src="https://github.com/0nsh/doggo/actions/workflows/test.yaml/badge.svg" alt="Test">
</a>
<a href="https://pypi.org/project/doggo" target="_blank">
<img src="https://img.shields.io/pypi/v/doggo?color=%2334D058&label=pypi%20package" alt="Package version">
</a>
</p>
<hr>
Doggo is a CLI tool that uses AI to help you search for and organize images using natural language queries. Instead of remembering exact filenames, just describe what you're looking for!
## Features
- 🔍 **Semantic Search**: Find images by describing them in natural language
- 🗂️ **AI-Powered Organization**: Automatically organize images into intelligent categories
- ✏️ **Smart Renaming**: Generate descriptive filenames based on image content
- 🎯 **Smart Results**: AI-powered similarity matching
- 💻 **CLI Interface**: Simple command-line interface
- 📊 **Rich Output**: Beautiful, informative search results
## Demo
https://github.com/user-attachments/assets/568d7f3d-9ff6-4adb-89db-71455a174c46
## Usage
```bash
pip install doggo
```
## Quick Start
1. **Initialize Doggo:**
```bash
doggo init
```
2. **Configure your AI provider:**
**For OpenAI (default):**
```bash
doggo config set --api-key "sk-your-openai-api-key"
```
**For Ollama (local models):**
```bash
doggo config set --provider-url "http://localhost:11434/v1" \
--chat-model "gemma3:latest" \
--embedding-model "nomic-embed-text:latest"
```
**Custom OpenAI setup:**
```bash
doggo config set --provider-url "https://api.openai.com/v1" \
--chat-model "gpt-4" \
--embedding-model "text-embedding-ada-002" \
--api-key "sk-your-openai-api-key"
```
3. **View current configuration:**
```bash
doggo config show
```
4. **Index your images:**
```bash
doggo index /path/to/your/images
```
5. **Search naturally:**
```bash
doggo search "a cute dog playing in the park"
doggo search "sunset over mountains"
doggo search "people having dinner"
```
By default, Doggo shows the top 5 results and automatically opens the best match in your system's previewer. Use `--no-open` to disable auto-opening or `--limit` to change the number of results.
6. **Organize your images:**
```bash
# Organize images into AI-generated category folders
doggo organize /path/to/your/images
# Organize with descriptive filenames
doggo organize /path/to/your/images --rename
# Organize to a custom output directory
doggo organize /path/to/your/images --rename --output /path/to/organized
# Organize in place (within the same directory)
doggo organize /path/to/your/images --inplace
```
## Organizing Images
Doggo can intelligently organize your images using AI-generated categories and descriptive filenames:
### **AI-Generated Categories**
During indexing, Doggo analyzes each image and assigns it to a category (e.g., "flower", "dog", "landscape", "food"). When you run the organize command, images are automatically grouped into folders based on these categories.
### **Smart Renaming**
With the `--rename` flag, Doggo generates descriptive filenames based on the image content. Instead of generic names like "IMG_001.jpg", you get meaningful names like "red_rose_garden.jpg" or "golden_retriever_park.jpg".
### **Organization Options**
- **Default**: Creates an "organized" folder in the source directory
- **Custom output**: Use `--output` to specify a different destination
- **In-place**: Use `--inplace` to organize within the original directory
- **Combined**: Use `--rename` with any output option for descriptive filenames
### **Example Organization**
```
Before:
📁 photos/
├── IMG_001.jpg (a red rose)
├── DSC_123.jpg (a dog in park)
└── photo.jpg (sunset)
After:
📁 organized/
├── 📁 flower/
│ └── red_rose_garden.jpg
├── 📁 dog/
│ └── golden_retriever_park.jpg
└── 📁 landscape/
└── sunset_beach_view.jpg
```
## How it works
- **AI-Powered Indexing**: Doggo scans directories for images, uses AI vision models to generate detailed descriptions and categories of each image, and converts these descriptions into vector embeddings for semantic search capabilities. Supports both OpenAI and local Ollama models.
- **Vector Database Storage**: The tool stores image metadata, AI-generated descriptions, categories, and vector embeddings in a local ChromaDB database, enabling fast similarity-based retrieval and intelligent organization without needing to re-process images on each search.
- **Natural Language Search**: Users can search for images using descriptive queries like "cute dog playing in the park" - the system converts the query to a vector embedding and finds the most semantically similar images using vector similarity search.
- **Intelligent Organization**: Using the AI-generated categories and descriptions, Doggo can automatically organize images into meaningful folders and generate descriptive filenames, making it easy to find and manage large collections of images.
- **CLI Interface**: Provides a simple command-line interface with commands for initialization (doggo init), configuration (doggo config), indexing (doggo index <path>), searching (doggo search "query"), and organizing (doggo organize <path>) with rich output formatting and progress tracking.
## Configuration
Doggo supports multiple AI providers through a flexible configuration system:
### **Supported Providers**
- **OpenAI**: Cloud-based AI services (default)
- **Ollama**: Local AI models running on your machine
### **Configuration Options**
- `--provider-url`: AI provider endpoint (default: OpenAI)
- `--chat-model`: Model for image analysis and chat (default: gpt-4o)
- `--embedding-model`: Model for text embeddings (default: text-embedding-3-small)
- `--api-key`: API key (required for OpenAI, optional for Ollama)
### **Example Configurations**
**OpenAI with custom models:**
```bash
doggo config set --provider-url "https://api.openai.com/v1" \
--chat-model "gpt-4" \
--embedding-model "text-embedding-ada-002" \
--api-key "sk-your-key"
```
**Ollama with local models:**
```bash
doggo config set --provider-url "http://localhost:11434/v1" \
--chat-model "llama3.2:3b" \
--embedding-model "nomic-embed-text:latest"
```
**View current settings:**
```bash
doggo config show
```
### **Provider-Specific Notes**
- **OpenAI**: Requires API key, supports vision models for image analysis
- **Ollama**: No API key required, ensure Ollama is running locally
- **Vision Support**: Not all Ollama models support image analysis - use models like `llama3.2:3b` that have vision capabilities
## Contributing
- Contributions are welcome! Please feel free to submit a pull request.
- See open issues for ideas.
## License
MIT License - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "doggo",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "ai, cli, files, images, search, semantic",
"author": "n0lan",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/bc/78/1b08841d8701bd1c8cb444a26a9484edd61cc8c3dc2adbb0aa30569ed04c/doggo-0.3.0.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img src=\"./docs/doggo.png\" width=\"400\" height=\"200\" style=\"border-radius: 10px;\" alt=\"Doggo\">\n\n</p>\n<p align=\"center\">\n <em>Doggo \ud83d\udc15, your loyal digital companion who finds files the way you think about them.</em>\n</p>\n<p align=\"center\">\n<a href=\"https://github.com/0nsh/doggo/actions/workflows/test.yaml\" target=\"_blank\">\n <img src=\"https://github.com/0nsh/doggo/actions/workflows/test.yaml/badge.svg\" alt=\"Test\">\n</a>\n\n<a href=\"https://pypi.org/project/doggo\" target=\"_blank\">\n <img src=\"https://img.shields.io/pypi/v/doggo?color=%2334D058&label=pypi%20package\" alt=\"Package version\">\n</a>\n\n</p>\n<hr>\n\nDoggo is a CLI tool that uses AI to help you search for and organize images using natural language queries. Instead of remembering exact filenames, just describe what you're looking for! \n\n## Features\n\n- \ud83d\udd0d **Semantic Search**: Find images by describing them in natural language\n- \ud83d\uddc2\ufe0f **AI-Powered Organization**: Automatically organize images into intelligent categories\n- \u270f\ufe0f **Smart Renaming**: Generate descriptive filenames based on image content\n- \ud83c\udfaf **Smart Results**: AI-powered similarity matching\n- \ud83d\udcbb **CLI Interface**: Simple command-line interface\n- \ud83d\udcca **Rich Output**: Beautiful, informative search results\n\n## Demo\n\nhttps://github.com/user-attachments/assets/568d7f3d-9ff6-4adb-89db-71455a174c46\n\n\n## Usage\n\n```bash\npip install doggo\n```\n\n## Quick Start\n\n1. **Initialize Doggo:**\n ```bash\n doggo init\n ```\n\n2. **Configure your AI provider:**\n \n **For OpenAI (default):**\n ```bash\n doggo config set --api-key \"sk-your-openai-api-key\"\n ```\n \n **For Ollama (local models):**\n ```bash\n doggo config set --provider-url \"http://localhost:11434/v1\" \\\n --chat-model \"gemma3:latest\" \\\n --embedding-model \"nomic-embed-text:latest\"\n ```\n \n **Custom OpenAI setup:**\n ```bash\n doggo config set --provider-url \"https://api.openai.com/v1\" \\\n --chat-model \"gpt-4\" \\\n --embedding-model \"text-embedding-ada-002\" \\\n --api-key \"sk-your-openai-api-key\"\n ```\n\n3. **View current configuration:**\n ```bash\n doggo config show\n ```\n\n4. **Index your images:**\n ```bash\n doggo index /path/to/your/images\n ```\n\n5. **Search naturally:**\n ```bash\n doggo search \"a cute dog playing in the park\"\n doggo search \"sunset over mountains\"\n doggo search \"people having dinner\"\n ```\n \n By default, Doggo shows the top 5 results and automatically opens the best match in your system's previewer. Use `--no-open` to disable auto-opening or `--limit` to change the number of results.\n\n6. **Organize your images:**\n ```bash\n # Organize images into AI-generated category folders\n doggo organize /path/to/your/images\n \n # Organize with descriptive filenames\n doggo organize /path/to/your/images --rename\n \n # Organize to a custom output directory\n doggo organize /path/to/your/images --rename --output /path/to/organized\n \n # Organize in place (within the same directory)\n doggo organize /path/to/your/images --inplace\n ```\n\n## Organizing Images\n\nDoggo can intelligently organize your images using AI-generated categories and descriptive filenames:\n\n### **AI-Generated Categories**\nDuring indexing, Doggo analyzes each image and assigns it to a category (e.g., \"flower\", \"dog\", \"landscape\", \"food\"). When you run the organize command, images are automatically grouped into folders based on these categories.\n\n### **Smart Renaming**\nWith the `--rename` flag, Doggo generates descriptive filenames based on the image content. Instead of generic names like \"IMG_001.jpg\", you get meaningful names like \"red_rose_garden.jpg\" or \"golden_retriever_park.jpg\".\n\n### **Organization Options**\n- **Default**: Creates an \"organized\" folder in the source directory\n- **Custom output**: Use `--output` to specify a different destination\n- **In-place**: Use `--inplace` to organize within the original directory\n- **Combined**: Use `--rename` with any output option for descriptive filenames\n\n### **Example Organization**\n```\nBefore:\n\ud83d\udcc1 photos/\n \u251c\u2500\u2500 IMG_001.jpg (a red rose)\n \u251c\u2500\u2500 DSC_123.jpg (a dog in park)\n \u2514\u2500\u2500 photo.jpg (sunset)\n\nAfter:\n\ud83d\udcc1 organized/\n \u251c\u2500\u2500 \ud83d\udcc1 flower/\n \u2502 \u2514\u2500\u2500 red_rose_garden.jpg\n \u251c\u2500\u2500 \ud83d\udcc1 dog/\n \u2502 \u2514\u2500\u2500 golden_retriever_park.jpg\n \u2514\u2500\u2500 \ud83d\udcc1 landscape/\n \u2514\u2500\u2500 sunset_beach_view.jpg\n```\n\n## How it works\n\n- **AI-Powered Indexing**: Doggo scans directories for images, uses AI vision models to generate detailed descriptions and categories of each image, and converts these descriptions into vector embeddings for semantic search capabilities. Supports both OpenAI and local Ollama models.\n\n- **Vector Database Storage**: The tool stores image metadata, AI-generated descriptions, categories, and vector embeddings in a local ChromaDB database, enabling fast similarity-based retrieval and intelligent organization without needing to re-process images on each search.\n\n- **Natural Language Search**: Users can search for images using descriptive queries like \"cute dog playing in the park\" - the system converts the query to a vector embedding and finds the most semantically similar images using vector similarity search.\n\n- **Intelligent Organization**: Using the AI-generated categories and descriptions, Doggo can automatically organize images into meaningful folders and generate descriptive filenames, making it easy to find and manage large collections of images.\n\n- **CLI Interface**: Provides a simple command-line interface with commands for initialization (doggo init), configuration (doggo config), indexing (doggo index <path>), searching (doggo search \"query\"), and organizing (doggo organize <path>) with rich output formatting and progress tracking.\n\n\n## Configuration\n\nDoggo supports multiple AI providers through a flexible configuration system:\n\n### **Supported Providers**\n\n- **OpenAI**: Cloud-based AI services (default)\n- **Ollama**: Local AI models running on your machine\n\n### **Configuration Options**\n\n- `--provider-url`: AI provider endpoint (default: OpenAI)\n- `--chat-model`: Model for image analysis and chat (default: gpt-4o)\n- `--embedding-model`: Model for text embeddings (default: text-embedding-3-small)\n- `--api-key`: API key (required for OpenAI, optional for Ollama)\n\n### **Example Configurations**\n\n**OpenAI with custom models:**\n```bash\ndoggo config set --provider-url \"https://api.openai.com/v1\" \\\n --chat-model \"gpt-4\" \\\n --embedding-model \"text-embedding-ada-002\" \\\n --api-key \"sk-your-key\"\n```\n\n**Ollama with local models:**\n```bash\ndoggo config set --provider-url \"http://localhost:11434/v1\" \\\n --chat-model \"llama3.2:3b\" \\\n --embedding-model \"nomic-embed-text:latest\"\n```\n\n**View current settings:**\n```bash\ndoggo config show\n```\n\n### **Provider-Specific Notes**\n\n- **OpenAI**: Requires API key, supports vision models for image analysis\n- **Ollama**: No API key required, ensure Ollama is running locally\n- **Vision Support**: Not all Ollama models support image analysis - use models like `llama3.2:3b` that have vision capabilities\n\n## Contributing\n\n- Contributions are welcome! Please feel free to submit a pull request.\n- See open issues for ideas.\n\n## License\n\nMIT License - see the [LICENSE](LICENSE) file for details.",
"bugtrack_url": null,
"license": "MIT",
"summary": "Your loyal digital companion who finds files the way you think about them",
"version": "0.3.0",
"project_urls": {
"Homepage": "https://github.com/0nsh/doggo",
"Issues": "https://github.com/0nsh/doggo",
"Repository": "https://github.com/0nsh/doggo"
},
"split_keywords": [
"ai",
" cli",
" files",
" images",
" search",
" semantic"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "67130a7ebd691df11963d25c0b750beadfd7d63193c7791c7cbba119c94478d6",
"md5": "e7998b0f46003a4a12645e164125698b",
"sha256": "adc2df2a62f05e989ee6d2da34f4b162ffab7efda8101ea4fd87ac35d7812677"
},
"downloads": -1,
"filename": "doggo-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e7998b0f46003a4a12645e164125698b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 17557,
"upload_time": "2025-07-14T02:14:20",
"upload_time_iso_8601": "2025-07-14T02:14:20.085088Z",
"url": "https://files.pythonhosted.org/packages/67/13/0a7ebd691df11963d25c0b750beadfd7d63193c7791c7cbba119c94478d6/doggo-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bc781b08841d8701bd1c8cb444a26a9484edd61cc8c3dc2adbb0aa30569ed04c",
"md5": "6d47a4b2caf0f98aecc7195b8de5a8de",
"sha256": "d8c93b5198384c66de7967a5631cab8649c013568f01023d5c6827c93698fea8"
},
"downloads": -1,
"filename": "doggo-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "6d47a4b2caf0f98aecc7195b8de5a8de",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 484560,
"upload_time": "2025-07-14T02:14:21",
"upload_time_iso_8601": "2025-07-14T02:14:21.272424Z",
"url": "https://files.pythonhosted.org/packages/bc/78/1b08841d8701bd1c8cb444a26a9484edd61cc8c3dc2adbb0aa30569ed04c/doggo-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-14 02:14:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "0nsh",
"github_project": "doggo",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "doggo"
}
