{"id":50269580,"url":"https://github.com/cryptaliagy/pokeplanner","last_synced_at":"2026-05-27T16:04:40.171Z","repository":{"id":346177463,"uuid":"1188288429","full_name":"cryptaliagy/pokeplanner","owner":"cryptaliagy","description":"The most over-engineered Pokemon team planner you've ever seen. Available as CLI, REST API, and gRPC","archived":false,"fork":false,"pushed_at":"2026-03-23T04:33:38.000Z","size":237,"stargazers_count":0,"open_issues_count":14,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-23T07:36:08.225Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","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/cryptaliagy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-21T21:46:43.000Z","updated_at":"2026-03-23T04:06:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cryptaliagy/pokeplanner","commit_stats":null,"previous_names":["cryptaliagy/pokeplanner"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/cryptaliagy/pokeplanner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cryptaliagy%2Fpokeplanner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cryptaliagy%2Fpokeplanner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cryptaliagy%2Fpokeplanner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cryptaliagy%2Fpokeplanner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cryptaliagy","download_url":"https://codeload.github.com/cryptaliagy/pokeplanner/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cryptaliagy%2Fpokeplanner/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33573271,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-27T02:00:06.184Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2026-05-27T16:04:13.005Z","updated_at":"2026-05-27T16:04:40.163Z","avatar_url":"https://github.com/cryptaliagy.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PokePlanner\n\nA competitive Pokemon team planner built in Rust. Given a game (or set of games), PokePlanner fetches every available Pokemon from [PokeAPI](https://pokeapi.co), scores them on offensive coverage, defensive resilience, and base stats, and returns optimally balanced teams.\n\n## Key Features\n\n- **Optimal team planning** -- brute-force search for small pools (N\u003c=25), greedy beam search for larger ones. Configurable `top_k` results.\n- **Move selection** -- recommends 4 moves per team member: 2 STAB + 2 coverage, filtered for safety (no recoil, no self-debuff). Generation-aware learnset fallback when data is sparse.\n- **Counter-team analysis** -- supply an opponent's team and PokePlanner finds the best response.\n- **Type coverage analysis** -- evaluate offensive and defensive type matchups for any team composition.\n- **Multi-game support** -- combine Pokemon pools across games (e.g., `--game red-blue,gold-silver`).\n- **Three interfaces** -- CLI, REST API, and gRPC API, all backed by the same service layer.\n- **Aggressive caching** -- disk-cached PokeAPI responses with 1-year TTL, rate limiting, and a CLI for cache management.\n- **Observability** -- structured logging, distributed tracing (OpenTelemetry), and 13 metrics instruments. Optional OTLP export.\n\n## Navigation\n\n| Document | What's in it |\n|---|---|\n| [Architecture](docs/ARCHITECTURE.md) | System design, data flow, crate dependency graph |\n| [Observability](docs/OBSERVABILITY.md) | Metrics catalog, tracing, logging, correlation model |\n| [Cost Function](docs/COST_FUNCTION.md) | Team scoring algorithm (offensive + defensive + BST) |\n| [Caching](docs/CACHING.md) | How caching works, rate limiting, cache CLI, bypass |\n| [Dependencies](docs/DEPENDENCIES.md) | Dependency choices and rationale |\n| [Structure](docs/STRUCTURE.md) | Repository layout, file-by-file |\n| [FAQ](docs/FAQ.md) | Why three APIs? How does the planner work? And more |\n| [Runbook](ops/RUNBOOK.md) | Production incident diagnosis playbook |\n| [Dashboards](dashboards/README.md) | Grafana dashboard import and metric mapping |\n| [Contributing](CONTRIBUTING.md) | How to contribute, dev setup, testing, PR workflow |\n\n## Quickstart\n\n### With Nix (recommended)\n\nPokePlanner includes a Nix flake with all dependencies (Rust toolchain, protobuf, just, etc.):\n\n```bash\n# Enter the dev shell (or use direnv with the included .envrc)\nnix develop\n\n# Run CI checks\njust ci\n\n# Plan a team\ncargo run -p pokeplanner-cli -- plan-team --game red-blue\n```\n\n### Without Nix\n\nRequires: Rust stable, `protoc` (protobuf compiler), and `just` (command runner).\n\n```bash\ncargo build\ncargo test\n```\n\n### CLI Examples\n\n```bash\n# Browse games and Pokemon\ncargo run -p pokeplanner-cli -- list-games\ncargo run -p pokeplanner-cli -- game-pokemon red-blue --min-bst 400\ncargo run -p pokeplanner-cli -- pokemon show charizard --show-learnset\n\n# Search Pokemon by type, stats, name\ncargo run -p pokeplanner-cli -- pokemon search --type fire --min-bst 500\n\n# Browse and search moves\ncargo run -p pokeplanner-cli -- moves show flamethrower\ncargo run -p pokeplanner-cli -- moves search charizard --game red-blue --type fire\n\n# Plan teams\ncargo run -p pokeplanner-cli -- plan-team --game red-blue\ncargo run -p pokeplanner-cli -- plan-team --game red-blue,gold-silver --min-bst 400\ncargo run -p pokeplanner-cli -- plan-team --game sword-shield --learnset-game sword-shield\n\n# Analyze an existing team\ncargo run -p pokeplanner-cli -- analyze-team charizard,blastoise,venusaur\n\n# Manage unusable list\ncargo run -p pokeplanner-cli -- unusable add magikarp,metapod\ncargo run -p pokeplanner-cli -- plan-team --game red-blue  # excludes magikarp and metapod\n\n# Cache management\ncargo run -p pokeplanner-cli -- cache stats\ncargo run -p pokeplanner-cli -- cache populate game red-blue\ncargo run -p pokeplanner-cli -- cache populate all\n```\n\n### Start the APIs\n\n```bash\n# REST API (default port 3000)\ncargo run -p pokeplanner-api-rest\n\n# gRPC API (default port 50051)\ncargo run -p pokeplanner-api-grpc\n\n# With observability export\ncargo run -p pokeplanner-api-rest -- --otlp-endpoint http://localhost:4317 --log-format json\n```\n\n## Project Structure\n\n| Crate | Description |\n|---|---|\n| `pokeplanner-core` | Shared types -- models, errors, job and team types |\n| `pokeplanner-pokeapi` | PokeAPI HTTP client with disk caching and rate limiting |\n| `pokeplanner-storage` | Storage trait + JSON file implementation |\n| `pokeplanner-service` | Business logic, team planner, move selector, type chart |\n| `pokeplanner-telemetry` | Shared observability initialization (tracing, OTEL, metrics) |\n| `pokeplanner-api-rest` | Axum REST server (port 3000) |\n| `pokeplanner-api-grpc` | Tonic gRPC server (port 50051) |\n| `pokeplanner-cli` | Clap CLI (`pokeplanner` binary) |\n\nSee [docs/STRUCTURE.md](docs/STRUCTURE.md) for the full file-by-file layout.\n\n## Development\n\n```bash\njust ci          # Run all checks (format, lint, check, test, build)\njust fmt         # Auto-fix formatting\njust test        # Run tests only\njust audit       # Security audit dependencies\njust install-hooks  # Install pre-commit hook (format + lint + check)\n```\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcryptaliagy%2Fpokeplanner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcryptaliagy%2Fpokeplanner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcryptaliagy%2Fpokeplanner/lists"}