{"id":38097526,"url":"https://github.com/bkataru/spotigo","last_synced_at":"2026-01-16T21:04:25.097Z","repository":{"id":254529715,"uuid":"766281890","full_name":"bkataru/spotigo","owner":"bkataru","description":"AI-powered local music intelligence platform with a task runner server core to retrieve and backup spotify account data to storage(s) at set periodic intervals","archived":false,"fork":false,"pushed_at":"2026-01-14T19:56:15.000Z","size":204,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-14T19:57:56.476Z","etag":null,"topics":["ai","backup","cron","data","go","intelligence","local-llm","music","ollama","rag","runner","spotify","task-runner","tool-calling"],"latest_commit_sha":null,"homepage":"","language":"Go","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/bkataru.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":"2024-03-02T20:36:19.000Z","updated_at":"2026-01-14T19:54:19.000Z","dependencies_parsed_at":"2024-08-24T04:44:05.141Z","dependency_job_id":"d7666c49-94e5-4447-a887-4cc70e779b77","html_url":"https://github.com/bkataru/spotigo","commit_stats":null,"previous_names":["bkataru/spotigo"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/bkataru/spotigo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkataru%2Fspotigo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkataru%2Fspotigo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkataru%2Fspotigo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkataru%2Fspotigo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bkataru","download_url":"https://codeload.github.com/bkataru/spotigo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkataru%2Fspotigo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28482495,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"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":["ai","backup","cron","data","go","intelligence","local-llm","music","ollama","rag","runner","spotify","task-runner","tool-calling"],"created_at":"2026-01-16T21:04:24.934Z","updated_at":"2026-01-16T21:04:25.027Z","avatar_url":"https://github.com/bkataru.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Spotigo\n\n[![CI](https://github.com/bkataru/spotigo/actions/workflows/ci.yml/badge.svg)](https://github.com/bkataru/spotigo/actions/workflows/ci.yml)\n[![Go Version](https://img.shields.io/badge/Go-1.24+-00ADD8?style=flat\u0026logo=go)](https://go.dev/)\n[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Go Report Card](https://goreportcard.com/badge/github.com/bkataru/spotigo)](https://goreportcard.com/report/github.com/bkataru/spotigo)\n[![Go Reference](https://pkg.go.dev/badge/github.com/bkataru/spotigo.svg)](https://pkg.go.dev/github.com/bkataru/spotigo)\n\n**A powerful command-line application and Go library for AI-powered Spotify library management with local RAG capabilities.**\n\nSpotigo provides both a comprehensive CLI application for end users and a powerful Go library for developers. Interact with Spotify APIs, manage local music libraries, and implement RAG (Retrieval-Augmented Generation) functionality with Ollama for AI-powered music analysis.\n\n## Quick Start\n\n### As a CLI Application\n\n1. **Install Spotigo CLI:**\n   ```bash\n   # Download pre-built binary from releases\n   # OR build from source:\n   git clone https://github.com/bkataru/spotigo.git\n   cd spotigo\n   go build -o spotigo ./cmd/spotigo\n   ```\n\n2. **Authenticate with Spotify:**\n   ```bash\n   spotigo auth\n   ```\n\n3. **Backup your Spotify library:**\n   ```bash\n   spotigo backup\n   ```\n\n4. **Chat with your music library:**\n   ```bash\n   spotigo chat\n   ```\n\n### As a Go Library\n\n```bash\ngo get github.com/bkataru/spotigo@latest\n```\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"log\"\n\n    \"github.com/bkataru/spotigo/internal/spotify\"\n    \"github.com/bkataru/spotigo/internal/ollama\"\n    \"github.com/bkataru/spotigo/internal/rag\"\n)\n\nfunc main() {\n    ctx := context.Background()\n\n    // Initialize Spotify client\n    spotifyClient, err := spotify.NewClient(spotify.Config{\n        ClientID:     \"your_client_id\",\n        ClientSecret: \"your_client_secret\",\n        RedirectURI:  \"http://127.0.0.1:8888/callback\",\n    })\n    if err != nil {\n        log.Fatal(err)\n    }\n\n    // Initialize Ollama client\n    ollamaClient := ollama.NewClient(\"http://localhost:11434\", 30*time.Second)\n\n    // Initialize RAG store\n    store := rag.NewStore(ollamaClient, \"nomic-embed-text-v2-moe\", \"./data/store.json\")\n}\n```\n\n## CLI Usage\n\nSpotigo comes with a comprehensive command-line interface for managing your Spotify library and performing AI-powered analysis.\n\n### Available Commands\n\n```bash\n# Backup and restore Spotify library\nspotigo backup                    # Backup your library\nspotigo backup list              # List available backups\nspotigo backup restore \u003cid\u003e      # Restore from backup\nspotigo backup status            # Show backup status\n\n# AI-powered chat about your music\nspotigo chat                     # Start interactive chat session\nspotigo chat --tools=true        # Enable function calling (default)\nspotigo chat --data-dir ./data   # Specify data directory\n\n# Semantic search across music library\nspotigo search \"rock music\"      # Search with natural language\nspotigo search index             # Build/rebuild search index\nspotigo search status            # Show search index status\n\n# Statistics and insights\nspotigo stats                    # Overall listening statistics\nspotigo stats top                # Top tracks and artists\nspotigo stats genres             # Genre distribution analysis\nspotigo stats playlists          # Playlist analysis\n\n# Authentication management\nspotigo auth                     # Authenticate with Spotify\nspotigo auth status              # Check authentication status\nspotigo auth logout              # Remove credentials\n\n# Ollama model management\nspotigo models list              # List recommended models\nspotigo models status            # Show installed models\nspotigo models pull              # Pull recommended models\n\n# Interactive TUI mode\nspotigo --tui                    # Launch terminal UI interface\n```\n\n### Configuration\n\nCreate `~/.spotigo.yaml`:\n\n```yaml\nspotify:\n  client_id: \"your_spotify_client_id\"\n  client_secret: \"your_spotify_client_secret\"\n  redirect_uri: \"http://127.0.0.1:8888/callback\"\n\nollama:\n  host: \"http://localhost:11434\"\n  timeout: 30\n\nstorage:\n  data_dir: \"./data\"\n  backup_dir: \"./data/backups\"\n  embeddings_dir: \"./data/embeddings\"\n\nbackup:\n  schedule: \"daily\"\n  retain_days: 30\n```\n\nUse a custom configuration file:\n```bash\nspotigo --config /path/to/config.yaml backup\n```\n\n## Features\n\n- **Spotify API Integration** - Comprehensive Go client for Spotify Web API with OAuth2 authentication\n- **CLI Application** - Full-featured command-line interface for end users\n- **AI Chat with Function Calling** - Natural language queries with structured JSON tool execution\n- **RAG Vector Store** - In-memory vector store with semantic search capabilities\n- **Ollama Integration** - Client for local LLM inference with chat and embedding generation\n- **JSON Query Engine** - Powerful structured queries for music data (filtering, sorting, aggregation)\n- **Local Storage** - Encrypted token storage and persistent data management\n- **Semantic Search** - Vector-based similarity search across music metadata\n- **Batch Processing** - Parallel embedding generation and efficient bulk operations\n- **Type-Safe APIs** - Well-documented Go interfaces with comprehensive error handling\n- **Terminal UI** - Interactive menu-driven interface for all features\n\n## Installation\n\n### Prerequisites\n\n- Go 1.24+ (for building from source)\n- Ollama (optional, for AI functionality)\n- Spotify Developer Account (for API access)\n\n### Install as CLI Application\n\n**Option 1: Download pre-built binary**\n- Visit the [releases page](https://github.com/bkataru/spotigo/releases)\n- Download the binary for your platform\n- Add to your PATH\n\n**Option 2: Build from source**\n```bash\ngit clone https://github.com/bkataru/spotigo.git\ncd spotigo\ngo build -o spotigo ./cmd/spotigo\nsudo mv spotigo /usr/local/bin/  # or add to your PATH\n```\n\n### Install as Go Library\n\n```bash\ngo get github.com/bkataru/spotigo@latest\n```\n\n## API Reference\n\n### Spotify Client\n\n```go\n// Create Spotify client\nclient := spotify.NewClient(spotify.Config{\n    ClientID:     \"your_client_id\",\n    ClientSecret: \"your_client_secret\",\n    RedirectURI:  \"http://127.0.0.1:8888/callback\",\n})\n\n// Get authentication URL\nauthURL := client.GetAuthURL(\"state\")\n\n// Handle OAuth callback\nerr := client.HandleCallback(ctx, \"state\", request)\n\n// Fetch user data\ntracks, err := client.GetSavedTracks(ctx)\nplaylists, err := client.GetPlaylists(ctx)\nartists, err := client.GetFollowedArtists(ctx)\n```\n\n### Ollama Client\n\n```go\n// Create Ollama client\nclient := ollama.NewClient(\"http://localhost:11434\", 30*time.Second)\n\n// Generate embeddings\nembedding, err := client.Embed(ctx, \"nomic-embed-text-v2-moe\", \"text to embed\")\n\n// Chat completion\nresponse, err := client.Chat(ctx, ollama.ChatRequest{\n    Model: \"granite4:1b\",\n    Messages: []ollama.Message{\n        {Role: \"user\", Content: \"Hello!\"},\n    },\n})\n```\n\n### RAG Store\n\n```go\n// Create vector store\nstore := rag.NewStore(ollamaClient, \"nomic-embed-text-v2-moe\", \"./data/store.json\")\n\n// Add documents\nerr := store.Add(ctx, rag.Document{\n    ID:      \"track_123\",\n    Type:    \"track\",\n    Content: \"Artist - Song Name\",\n    Metadata: map[string]string{\"genre\": \"rock\"},\n})\n\n// Semantic search\nresults, err := store.Search(ctx, \"upbeat rock music\", 10, \"track\")\n```\n\n### AI Chat with Tool Calling\n\nThe AI chat uses function calling to efficiently query your music library without loading all data into context.\n\n```bash\n# Start chat with tool calling enabled\nspotigo chat\n\n# Example conversation:\nYou: How many tracks do I have?\n🔧 Calling tool: get_library_stats\nSpotigo: You have 1,234 saved tracks, 25 playlists, and 42 followed artists.\n\nYou: Find my most popular Queen songs\n🔧 Calling tool: get_tracks_by_artist\n🔧 Calling tool: query_music_data\nSpotigo: Here are your top Queen tracks:\n1. \"Bohemian Rhapsody\" (popularity: 95)\n2. \"We Will Rock You\" (popularity: 90)\n...\n```\n\n**Available Tools:**\n- `get_library_stats` - Overall library statistics\n- `search_tracks` - Search by artist, song, album\n- `get_tracks_by_artist` - All tracks by specific artist\n- `get_recently_added_tracks` - Recently saved tracks\n- `get_all_artists` - List all unique artists\n- `get_playlist_by_name` - Find playlists\n- `query_music_data` - Custom queries with filters, sorting, aggregation\n\n**Why Function Calling?**\n- ✅ **Efficient** - Only retrieves relevant data, minimal context usage\n- ✅ **Accurate** - Structured queries are more precise than text embeddings\n- ✅ **Fast** - Direct JSON queries with caching\n- ✅ **Structured** - Preserves data relationships and schema\n\nFor detailed documentation on AI chat and tool calling, see [docs/TOOLS.md](docs/TOOLS.md).\n\n### JSON Query Engine\n\n```go\nimport \"github.com/bkataru/spotigo/internal/jsonquery\"\n\n// Create query engine\nengine := jsonquery.NewEngine(\"./data\")\n\n// Execute structured query\nresult := engine.Execute(jsonquery.Query{\n    Source:    \"saved_tracks.json\",\n    Operation: \"filter\",\n    Filters: []jsonquery.Filter{\n        {\n            Field:    \"track.popularity\",\n            Operator: \"gte\",\n            Value:    90,\n        },\n    },\n    SortBy:    \"track.popularity\",\n    SortOrder: \"desc\",\n    Limit:     10,\n})\n\n// Use music query helpers\nhelper := jsonquery.NewMusicQueryHelper(\"./data\")\nstats := helper.GetLibraryStats()\ntracks := helper.GetTracksByArtist(\"Queen\")\nrecent := helper.GetRecentlyAddedTracks(20)\n```\n\n## Supported Models\n\n### Embedding Models\n- `nomic-embed-text-v2-moe` - Recommended for embeddings\n- `qwen3-embedding:0.6b` - Smaller alternative\n- Any Ollama-compatible embedding model\n\n### Chat Models\n- `granite4:1b` - Balanced performance\n- `qwen3:0.6b` - Lightweight option\n- `granite4:350m` - Fast inference\n- Any Ollama-compatible chat model\n\n## Development\n\n### Setup Development Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/bkataru/spotigo.git\ncd spotigo\n\n# Install dependencies\ngo mod download\n\n# Run tests\ngo test ./...\n\n# Run linter\ngolangci-lint run\n\n# Build CLI\ngo build -o spotigo ./cmd/spotigo\n```\n\n### Project Structure\n\n```\nspotigo/\n├── cmd/spotigo/         # CLI application entry point\n├── internal/\n│   ├── config/          # Configuration management\n│   ├── crypto/          # Token encryption utilities\n│   ├── jsonutil/        # JSON utilities\n│   ├── ollama/          # Ollama API client\n│   ├── rag/             # RAG vector store\n│   ├── spotify/         # Spotify API client\n│   ├── storage/         # Local file storage\n│   └── cmd/             # CLI command implementations\n├── examples/            # Example usage (library and CLI)\n├── .github/workflows/   # CI/CD pipelines\n└── go.mod              # Module definition\n```\n\n## Architecture\n\n### Component Relationships\n\n```\n┌─────────────┐     ┌─────────────┐     ┌─────────────┐\n│   Spotify   │────\u003e│   Spotify   │────\u003e│   RAG       │\n│     API     │     │   Client    │     │   Store     │\n└─────────────┘     └─────────────┘     └─────────────┘\n                                             │\n                   ┌─────────────┐           │\n                   │   Ollama    │\u003c──────────┤\n                   │   Client    │           │\n                   └─────────────┘           │\n                         │                   │\n                   ┌─────────────┐     ┌─────────────┐\n                   │   Local     │     │   CLI/API   │\n                   │   Storage   │\u003c───\u003e│   Interface │\n                   └─────────────┘     └─────────────┘\n```\n\n### Security Features\n\n- **Token Encryption**: OAuth tokens encrypted using AES-256-GCM\n- **Local Processing**: All AI inference happens locally via Ollama\n- **No External Dependencies**: Minimal reliance on external services\n- **Type Safety**: Comprehensive Go interfaces with proper error handling\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Development Workflow\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/my-feature`\n3. Make your changes\n4. Run tests: `go test ./...`\n5. Run linter: `golangci-lint run`\n6. Commit your changes\n7. Open a Pull Request\n\n## Troubleshooting\n\n### Ollama Connection Issues\n\nEnsure Ollama is running:\n```bash\ncurl http://localhost:11434/api/tags\n```\n\n### Spotify Authentication Issues\n\nCheck your OAuth configuration and ensure your Spotify app has the correct redirect URI.\n\n### Build Issues\n\n```bash\n# Clean and rebuild\ngo mod tidy\ngo test ./...\n```\n\n## FAQ\n\n### General Questions\n\n**Q: Does this application send data to external servers?**\n\nA: No. All AI processing happens locally via Ollama. The application does not include telemetry or analytics.\n\n**Q: What Spotify data can I access?**\n\nA: The application supports read-only access to:\n- Saved tracks and albums\n- User playlists (including private ones)\n- Followed artists\n- Recently played tracks\n- Top tracks and artists\n\nThe application cannot modify your Spotify library or play music.\n\n**Q: Can I use this application offline?**\n\nA: After initial Spotify authentication, most features work offline:\n- Semantic search (with pre-generated embeddings)\n- Local data processing\n- RAG functionality (requires Ollama running locally)\n\nInternet access is required for:\n- Spotify OAuth authentication\n- Spotify API calls\n\n### Technical Questions\n\n**Q: How do I handle OAuth authentication?**\n\nA: The Spotify client provides methods for OAuth flow:\n```go\n// Get authentication URL\nauthURL := client.GetAuthURL(\"state\")\n\n// Handle callback\nerr := client.HandleCallback(ctx, \"state\", request)\n```\n\n**Q: How do I persist authentication tokens?**\n\nA: The Spotify client includes encrypted token storage:\n```go\nerr := client.SaveToken(\".spotify_token\")\n```\n\n**Q: What models are recommended for embeddings?**\n\nA: `nomic-embed-text-v2-moe` is recommended for embeddings, but any Ollama-compatible embedding model will work.\n\n**Q: How do I handle errors?**\n\nA: All library functions return proper Go errors with descriptive messages for easy debugging.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Acknowledgments\n\n- [Ollama](https://ollama.ai/) - Local LLM inference\n- [Spotify Web API](https://developer.spotify.com/) - Music data\n- [zmb3's Spotify library](https://github.com/zmb3/spotify) - Go client library","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbkataru%2Fspotigo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbkataru%2Fspotigo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbkataru%2Fspotigo/lists"}