imho 0.2.0__tar.gz

imho-0.2.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+uv.lock

imho-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 imho.run
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

imho-0.2.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.5
+Name: imho
+Version: 0.2.0
+Summary: Python client for the imho.run API: Steam games like any game, game facts, and finding a game from a description.
+Project-URL: Homepage, https://imho.run/developers
+Project-URL: Documentation, https://github.com/0x216/imho-mcp/tree/main/python#readme
+Project-URL: Repository, https://github.com/0x216/imho-mcp
+Project-URL: Issues, https://github.com/0x216/imho-mcp/issues
+Author-email: "imho.run" <admin@imho.run>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: game-recommendations,games,imho,mcp,recommender-system,steam
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.24
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.21; extra == 'test'
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# imho (Python client for imho.run)
+
+A small typed client for the [imho.run](https://imho.run) API for AI assistants:
+Steam games like any game you name, recommendations from several games with
+filters, facts about one game, what is trending and newly released on Steam,
+title search, and identifying a game from a description. It wraps the public
+REST endpoints under `https://imho.run/api/agent/` and the MCP endpoint
+`https://imho.run/mcp`. The API is free, read-only and needs no key.
+
+```bash
+pip install imho
+```
+
+Requires Python 3.9+ and [httpx](https://www.python-httpx.org/). Source,
+issues and the MCP setup for assistants: <https://github.com/0x216/imho-mcp>.
+
+## Usage
+
+```python
+from imho import ImhoClient
+
+with ImhoClient() as imho:
+    picks = imho.games_like("Hollow Knight", n=3)
+    for game in picks["results"]:
+        print(game["rank"], game["name"], "-", game["why"], game["price"]["text"])
+```
+
+```
+1 Hollow Knight: Silksong - Also Metroidvania and Souls-like, like Hollow Knight. 19.99 USD
+2 Ori and the Blind Forest: Definitive Edition - Also Metroidvania, like Hollow Knight. 4.99 USD
+3 Nine Sols - Metroidvania with Sekiro-style parry combat and Taoist myth. 14.99 USD
+```
+
+(Output from 2026-10-04. Rankings and prices change.)
+
+### games_like
+
+```python
+imho.games_like(
+    "Stardew Valley",       # name (typos, Russian titles OK), Steam appid or Steam store URL
+    n=10,                   # 1..20
+    lang="en",              # "en" or "ru": language of the `why` lines
+    free=False,             # only free-to-play games
+    coop=False,             # True = any co-op, "online" or "local" (same screen / split screen)
+    steam_deck=None,        # "verified" or "playable" (playable or better)
+)
+```
+
+Returns a dict with `seed` (the game that was matched), `other_matches`,
+`results` (each with `rank`, `appid`, `name`, `url`, `steam_url`, `why`,
+`year`, `price`, `steam_deck`, `reviews`, `genres`), `list_url` and
+`attribution`.
+
+### recommend
+
+For several games, more filters, or what the user wants in their own words:
+
+```python
+recs = imho.recommend(
+    ["Stardew Valley", "Terraria"],   # 1-3 seed games
+    n=10,                              # 1..24
+    preferences="cozy farming, no horror",   # free text, read as Steam tags
+    coop=True,                         # also "online" / "local"
+    exclude=["pvp", "grind"],          # pvp, microtransactions, hard, grind, early_access, vr_only
+    exclude_tags=["Anime"],            # Steam tags to leave out
+    year_min=2015, year_max=None,      # release years (year_max defaults to this year)
+    upcoming=False,                    # True: include unreleased games
+    popularity_bias=-0.5,              # -1 more niche ... 1 more popular
+    free=False, steam_deck=None, lang="en",
+)
+for game in recs["results"]:
+    print(game["name"], "-", game["why"])
+recs["preferences"]["prefer_tags"], recs["preferences"]["avoid_tags"]
+# (['Farming Sim'], ['Horror'])
+```
+
+To refine after the user reacts, call again with `liked=[...]` (fills free
+seed slots, 3 seeds in all) and `disliked=[...]` (never recommended again).
+
+### trending, new_releases, search_games
+
+```python
+imho.trending(kind="rising", n=10)      # or kind="breakouts" for new games taking off
+imho.new_releases(n=10)                 # well-rated releases of the last 30 days
+imho.new_releases(upcoming=True, coop=True)
+imho.search_games("hollow kn", n=5)     # appid, year and links per match
+```
+
+Trending picks carry `reviews_week` and `reviews_growth_pct`; new releases
+carry `release_date`. While trending data is still being collected,
+`trending()` returns `status: "collecting"` and an empty `results`.
+
+### game_facts
+
+```python
+facts = imho.game_facts("Hades")["game"]
+facts["summary"]["length"], facts["summary"]["difficulty"], facts["steam_deck"]
+# ('massive', 'challenging', 'verified')
+```
+
+Year, developers, genres, top tags, price, Steam Deck status, review numbers,
+Steam's short description and, when imho.run has one, a summary mined from
+player reviews (difficulty, length, session shape, co-op, hooks, dealbreakers).
+
+### find_game_by_description
+
+```python
+hit = imho.find_game_by_description(
+    "you play a cat in a cyberpunk city with a little drone",
+    platform="pc",          # pc, playstation, xbox, nintendo, sega, mobile, browser, arcade
+    year_min=None, year_max=None,
+    perspective=None,       # first, third, top_down, side
+)
+hit["confidence"], hit["results"][0]["name"]   # ('medium', 'Stray')
+hit["find_game_url"]   # imho.run/find-game with the description filled in
+```
+
+This one runs a language model on the server. It takes several seconds and is
+limited to 3 calls a minute and 20 a day per IP, so use it only when the title
+is unknown.
+
+### Async
+
+```python
+import asyncio
+from imho import AsyncImhoClient
+
+async def main() -> None:
+    async with AsyncImhoClient() as imho:
+        facts = await imho.game_facts("1145360")
+        print(facts["game"]["name"])
+
+asyncio.run(main())
+```
+
+### Any MCP tool
+
+`call_tool(name, arguments)` calls any tool on the MCP server and returns its
+structured result, and `list_tools()` returns the tool definitions. Use them
+for tools added to the server after this release.
+
+## Errors
+
+| Exception | When |
+| --- | --- |
+| `NotFoundError` | No game matched the query (HTTP 404). |
+| `BadRequestError` | A parameter is out of range or the query is empty (400/422), or an unknown MCP tool. |
+| `RateLimitError` | Over the limit (HTTP 429). `retry_after` holds the seconds to wait when known. |
+| `DisabledError` | The API is switched off on the server (503). |
+| `ToolError` | An MCP tool returned `isError` for another reason. |
+
+All of them subclass `ImhoError`, which has `detail`, `code` and `status`.
+
+## Limits and attribution
+
+30 requests a minute and 1,000 a day per IP; `find_game_by_description` 3 a
+minute and 20 a day; `recommend` 10 new (uncached) combinations a minute and
+200 a day. Responses are cached on the server.
+
+If you show the results to people, credit imho.run ("Recommendations by
+imho.run") and link each game's `url`. Every response has an `attribution`
+field with that wording.
+
+## Development
+
+```bash
+cd python
+uv run --with pytest --with pytest-asyncio --with-editable . pytest -q
+IMHO_LIVE=1 uv run --with pytest --with pytest-asyncio --with-editable . pytest -q -m live   # hits the real API
+```
+
+## License
+
+MIT. The client is MIT-licensed; the imho.run service and its data are covered
+by the [imho.run terms](https://imho.run/terms).

imho-0.2.0/README.md

@@ -0,0 +1,175 @@
+# imho (Python client for imho.run)
+
+A small typed client for the [imho.run](https://imho.run) API for AI assistants:
+Steam games like any game you name, recommendations from several games with
+filters, facts about one game, what is trending and newly released on Steam,
+title search, and identifying a game from a description. It wraps the public
+REST endpoints under `https://imho.run/api/agent/` and the MCP endpoint
+`https://imho.run/mcp`. The API is free, read-only and needs no key.
+
+```bash
+pip install imho
+```
+
+Requires Python 3.9+ and [httpx](https://www.python-httpx.org/). Source,
+issues and the MCP setup for assistants: <https://github.com/0x216/imho-mcp>.
+
+## Usage
+
+```python
+from imho import ImhoClient
+
+with ImhoClient() as imho:
+    picks = imho.games_like("Hollow Knight", n=3)
+    for game in picks["results"]:
+        print(game["rank"], game["name"], "-", game["why"], game["price"]["text"])
+```
+
+```
+1 Hollow Knight: Silksong - Also Metroidvania and Souls-like, like Hollow Knight. 19.99 USD
+2 Ori and the Blind Forest: Definitive Edition - Also Metroidvania, like Hollow Knight. 4.99 USD
+3 Nine Sols - Metroidvania with Sekiro-style parry combat and Taoist myth. 14.99 USD
+```
+
+(Output from 2026-10-04. Rankings and prices change.)
+
+### games_like
+
+```python
+imho.games_like(
+    "Stardew Valley",       # name (typos, Russian titles OK), Steam appid or Steam store URL
+    n=10,                   # 1..20
+    lang="en",              # "en" or "ru": language of the `why` lines
+    free=False,             # only free-to-play games
+    coop=False,             # True = any co-op, "online" or "local" (same screen / split screen)
+    steam_deck=None,        # "verified" or "playable" (playable or better)
+)
+```
+
+Returns a dict with `seed` (the game that was matched), `other_matches`,
+`results` (each with `rank`, `appid`, `name`, `url`, `steam_url`, `why`,
+`year`, `price`, `steam_deck`, `reviews`, `genres`), `list_url` and
+`attribution`.
+
+### recommend
+
+For several games, more filters, or what the user wants in their own words:
+
+```python
+recs = imho.recommend(
+    ["Stardew Valley", "Terraria"],   # 1-3 seed games
+    n=10,                              # 1..24
+    preferences="cozy farming, no horror",   # free text, read as Steam tags
+    coop=True,                         # also "online" / "local"
+    exclude=["pvp", "grind"],          # pvp, microtransactions, hard, grind, early_access, vr_only
+    exclude_tags=["Anime"],            # Steam tags to leave out
+    year_min=2015, year_max=None,      # release years (year_max defaults to this year)
+    upcoming=False,                    # True: include unreleased games
+    popularity_bias=-0.5,              # -1 more niche ... 1 more popular
+    free=False, steam_deck=None, lang="en",
+)
+for game in recs["results"]:
+    print(game["name"], "-", game["why"])
+recs["preferences"]["prefer_tags"], recs["preferences"]["avoid_tags"]
+# (['Farming Sim'], ['Horror'])
+```
+
+To refine after the user reacts, call again with `liked=[...]` (fills free
+seed slots, 3 seeds in all) and `disliked=[...]` (never recommended again).
+
+### trending, new_releases, search_games
+
+```python
+imho.trending(kind="rising", n=10)      # or kind="breakouts" for new games taking off
+imho.new_releases(n=10)                 # well-rated releases of the last 30 days
+imho.new_releases(upcoming=True, coop=True)
+imho.search_games("hollow kn", n=5)     # appid, year and links per match
+```
+
+Trending picks carry `reviews_week` and `reviews_growth_pct`; new releases
+carry `release_date`. While trending data is still being collected,
+`trending()` returns `status: "collecting"` and an empty `results`.
+
+### game_facts
+
+```python
+facts = imho.game_facts("Hades")["game"]
+facts["summary"]["length"], facts["summary"]["difficulty"], facts["steam_deck"]
+# ('massive', 'challenging', 'verified')
+```
+
+Year, developers, genres, top tags, price, Steam Deck status, review numbers,
+Steam's short description and, when imho.run has one, a summary mined from
+player reviews (difficulty, length, session shape, co-op, hooks, dealbreakers).
+
+### find_game_by_description
+
+```python
+hit = imho.find_game_by_description(
+    "you play a cat in a cyberpunk city with a little drone",
+    platform="pc",          # pc, playstation, xbox, nintendo, sega, mobile, browser, arcade
+    year_min=None, year_max=None,
+    perspective=None,       # first, third, top_down, side
+)
+hit["confidence"], hit["results"][0]["name"]   # ('medium', 'Stray')
+hit["find_game_url"]   # imho.run/find-game with the description filled in
+```
+
+This one runs a language model on the server. It takes several seconds and is
+limited to 3 calls a minute and 20 a day per IP, so use it only when the title
+is unknown.
+
+### Async
+
+```python
+import asyncio
+from imho import AsyncImhoClient
+
+async def main() -> None:
+    async with AsyncImhoClient() as imho:
+        facts = await imho.game_facts("1145360")
+        print(facts["game"]["name"])
+
+asyncio.run(main())
+```
+
+### Any MCP tool
+
+`call_tool(name, arguments)` calls any tool on the MCP server and returns its
+structured result, and `list_tools()` returns the tool definitions. Use them
+for tools added to the server after this release.
+
+## Errors
+
+| Exception | When |
+| --- | --- |
+| `NotFoundError` | No game matched the query (HTTP 404). |
+| `BadRequestError` | A parameter is out of range or the query is empty (400/422), or an unknown MCP tool. |
+| `RateLimitError` | Over the limit (HTTP 429). `retry_after` holds the seconds to wait when known. |
+| `DisabledError` | The API is switched off on the server (503). |
+| `ToolError` | An MCP tool returned `isError` for another reason. |
+
+All of them subclass `ImhoError`, which has `detail`, `code` and `status`.
+
+## Limits and attribution
+
+30 requests a minute and 1,000 a day per IP; `find_game_by_description` 3 a
+minute and 20 a day; `recommend` 10 new (uncached) combinations a minute and
+200 a day. Responses are cached on the server.
+
+If you show the results to people, credit imho.run ("Recommendations by
+imho.run") and link each game's `url`. Every response has an `attribution`
+field with that wording.
+
+## Development
+
+```bash
+cd python
+uv run --with pytest --with pytest-asyncio --with-editable . pytest -q
+IMHO_LIVE=1 uv run --with pytest --with pytest-asyncio --with-editable . pytest -q -m live   # hits the real API
+```
+
+## License
+
+MIT. The client is MIT-licensed; the imho.run service and its data are covered
+by the [imho.run terms](https://imho.run/terms).

imho-0.2.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "imho"
+dynamic = ["version"]
+description = "Python client for the imho.run API: Steam games like any game, game facts, and finding a game from a description."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "imho.run", email = "admin@imho.run" }]
+keywords = ["steam", "games", "game-recommendations", "recommender-system", "mcp", "imho"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Games/Entertainment",
+  "Topic :: Internet :: WWW/HTTP",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.24,<1"]
+
+[project.optional-dependencies]
+test = ["pytest>=7", "pytest-asyncio>=0.21"]
+
+[project.urls]
+Homepage = "https://imho.run/developers"
+Documentation = "https://github.com/0x216/imho-mcp/tree/main/python#readme"
+Repository = "https://github.com/0x216/imho-mcp"
+Issues = "https://github.com/0x216/imho-mcp/issues"
+
+[tool.hatch.version]
+path = "src/imho/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/imho"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/imho", "tests", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+markers = ["live: calls the real imho.run API (set IMHO_LIVE=1)"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B"]
+
+[tool.mypy]
+strict = true
+python_version = "3.10"

imho-0.2.0/src/imho/__init__.py

@@ -0,0 +1,31 @@
+"""Python client for the imho.run agent API (Steam game recommendations).
+
+>>> from imho import ImhoClient
+>>> with ImhoClient() as imho:
+...     for pick in imho.games_like("Hollow Knight", n=3)["results"]:
+...         print(pick["rank"], pick["name"], "-", pick["why"])
+"""
+
+from ._version import __version__
+from .client import DEFAULT_BASE_URL, AsyncImhoClient, ImhoClient
+from .errors import (
+    BadRequestError,
+    DisabledError,
+    ImhoError,
+    NotFoundError,
+    RateLimitError,
+    ToolError,
+)
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "AsyncImhoClient",
+    "BadRequestError",
+    "DisabledError",
+    "ImhoClient",
+    "ImhoError",
+    "NotFoundError",
+    "RateLimitError",
+    "ToolError",
+    "__version__",
+]

imho-0.2.0/src/imho/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"