imho 0.2.0__py3-none-any.whl

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/_version.py

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

imho/client.py

@@ -0,0 +1,597 @@
+"""Sync and async clients for the imho.run agent API.
+
+Most methods use the REST endpoints under ``/api/agent/``.
+``find_game_by_description`` exists only as an MCP tool, so it (and
+:meth:`call_tool` for any other tool) goes through the MCP endpoint with a
+single stateless JSON-RPC request.
+"""
+
+from __future__ import annotations
+
+import itertools
+import json
+import re
+from typing import Any, Dict, List, Mapping, Optional, Sequence, Tuple, Union, cast
+
+import httpx
+
+from ._version import __version__
+from .errors import (
+    BadRequestError,
+    DisabledError,
+    ImhoError,
+    NotFoundError,
+    RateLimitError,
+    ToolError,
+)
+from .types import (
+    CoopMode,
+    Exclude,
+    FindGameResult,
+    GameFactsResult,
+    GamesLikeResult,
+    Lang,
+    NewReleasesResult,
+    Perspective,
+    Platform,
+    RecommendResult,
+    SearchResult,
+    SteamDeck,
+    TrendingKind,
+    TrendingResult,
+)
+
+DEFAULT_BASE_URL = "https://imho.run"
+DEFAULT_TIMEOUT = 30.0
+# find_game_by_description runs a language model; give it more room.
+FIND_TIMEOUT = 90.0
+MCP_PROTOCOL_VERSION = "2025-06-18"
+USER_AGENT = f"imho-python/{__version__} (+https://github.com/0x216/imho-mcp)"
+
+_RATE_TEXT = re.compile(r"Too many requests\. Retry after (\d+(?:\.\d+)?)s", re.I)
+_ids = itertools.count(1)
+
+Coop = Union[bool, CoopMode]
+Params = List[Tuple[str, str]]
+Request = Tuple[str, Params]
+
+
+# ── request building (shared by both clients) ──────────────────────────────
+
+
+def _check_n(n: int, maximum: int) -> str:
+    if not 1 <= n <= maximum:
+        raise ValueError(f"n must be between 1 and {maximum}")
+    return str(n)
+
+
+def _flag(value: bool) -> str:
+    return "true" if value else "false"
+
+
+def _coop_value(coop: Coop) -> Optional[str]:
+    if coop is False:
+        return None
+    if coop is True:
+        return "true"
+    if coop in ("online", "local"):
+        return cast(str, coop)
+    raise ValueError("coop must be True, False, 'online' or 'local'")
+
+
+def _common_filters(
+    params: Params, free: bool, coop: Coop, steam_deck: Optional[SteamDeck]
+) -> None:
+    if free:
+        params.append(("free", "true"))
+    coop_value = _coop_value(coop)
+    if coop_value is not None:
+        params.append(("coop", coop_value))
+    if steam_deck is not None:
+        params.append(("deck", steam_deck))
+
+
+def _games_like_request(
+    game: str, n: int, lang: Lang, free: bool, coop: Coop, steam_deck: Optional[SteamDeck]
+) -> Request:
+    params: Params = [("q", game), ("n", _check_n(n, 20)), ("lang", lang)]
+    _common_filters(params, free, coop, steam_deck)
+    return "/api/agent/games-like", params
+
+
+def _game_facts_request(game: str, lang: Lang) -> Request:
+    return "/api/agent/game-facts", [("q", game), ("lang", lang)]
+
+
+def _recommend_request(
+    seeds: Sequence[str],
+    *,
+    n: int,
+    lang: Lang,
+    liked: Sequence[str],
+    disliked: Sequence[str],
+    preferences: Optional[str],
+    free: bool,
+    coop: Coop,
+    steam_deck: Optional[SteamDeck],
+    exclude: Sequence[Exclude],
+    exclude_tags: Sequence[str],
+    year_min: Optional[int],
+    year_max: Optional[int],
+    upcoming: bool,
+    popularity_bias: float,
+) -> Request:
+    if isinstance(seeds, str):
+        seeds = [seeds]
+    if not seeds and not liked:
+        raise ValueError("give at least one seed game (or liked games)")
+    if len(seeds) > 3:
+        raise ValueError("at most 3 seeds; pass more games as liked=")
+    if not -1.0 <= popularity_bias <= 1.0:
+        raise ValueError("popularity_bias must be between -1 and 1")
+    params: Params = [("seed", s) for s in seeds]
+    params += [("n", _check_n(n, 24)), ("lang", lang)]
+    _common_filters(params, free, coop, steam_deck)
+    params += [("exclude", e) for e in exclude]
+    params += [("exclude_tags", t) for t in exclude_tags]
+    params += [("liked", g) for g in liked]
+    params += [("disliked", g) for g in disliked]
+    if preferences:
+        params.append(("preferences", preferences))
+    if year_min is not None:
+        params.append(("year_min", str(year_min)))
+    if year_max is not None:
+        params.append(("year_max", str(year_max)))
+    if upcoming:
+        params.append(("upcoming", "true"))
+    if popularity_bias:
+        params.append(("popularity_bias", str(popularity_bias)))
+    return "/api/agent/recommend", params
+
+
+def _trending_request(kind: TrendingKind, n: int, lang: Lang) -> Request:
+    if kind not in ("rising", "breakouts"):
+        raise ValueError("kind must be 'rising' or 'breakouts'")
+    return "/api/agent/trending", [("kind", kind), ("n", _check_n(n, 20)), ("lang", lang)]
+
+
+def _new_releases_request(upcoming: bool, coop: bool, n: int, lang: Lang) -> Request:
+    params: Params = [("n", _check_n(n, 20)), ("lang", lang)]
+    if upcoming:
+        params.append(("upcoming", _flag(upcoming)))
+    if coop:
+        params.append(("coop", _flag(coop)))
+    return "/api/agent/new-releases", params
+
+
+def _search_request(query: str, n: int) -> Request:
+    if len(query.strip()) < 2:
+        raise ValueError("query must be at least 2 characters")
+    return "/api/agent/search", [("q", query), ("n", _check_n(n, 10))]
+
+
+def _find_args(
+    description: str,
+    lang: Lang,
+    platform: Optional[Platform],
+    year_min: Optional[int],
+    year_max: Optional[int],
+    perspective: Optional[Perspective],
+) -> Dict[str, Any]:
+    args: Dict[str, Any] = {"description": description, "lang": lang}
+    for key, value in (
+        ("platform", platform),
+        ("year_min", year_min),
+        ("year_max", year_max),
+        ("perspective", perspective),
+    ):
+        if value is not None:
+            args[key] = value
+    return args
+
+
+def _rpc(method: str, params: Optional[Mapping[str, Any]] = None) -> Dict[str, Any]:
+    body: Dict[str, Any] = {"jsonrpc": "2.0", "id": next(_ids), "method": method}
+    if params is not None:
+        body["params"] = dict(params)
+    return body
+
+
+def _tool_call(name: str, arguments: Optional[Mapping[str, Any]]) -> Dict[str, Any]:
+    return _rpc("tools/call", {"name": name, "arguments": dict(arguments or {})})
+
+
+_MCP_HEADERS = {
+    "Accept": "application/json, text/event-stream",
+    "MCP-Protocol-Version": MCP_PROTOCOL_VERSION,
+}
+
+
+# ── response handling ──────────────────────────────────────────────────────
+
+
+def _retry_after(resp: httpx.Response) -> Optional[float]:
+    value = resp.headers.get("Retry-After")
+    try:
+        return float(value) if value is not None else None
+    except ValueError:
+        return None
+
+
+def _raise_for_rest(resp: httpx.Response) -> Dict[str, Any]:
+    try:
+        data = resp.json()
+    except ValueError:
+        data = None
+    if resp.status_code < 400 and isinstance(data, dict):
+        return data
+    detail = resp.text[:500] or resp.reason_phrase
+    code: Optional[str] = None
+    if isinstance(data, dict):
+        code = data.get("error") if isinstance(data.get("error"), str) else None
+        if isinstance(data.get("detail"), str):
+            detail = data["detail"]
+        elif data.get("detail") is not None:  # FastAPI validation errors
+            detail = str(data["detail"])
+    status = resp.status_code
+    if status == 429 or code == "rate_limited":
+        raise RateLimitError(detail, status=status, retry_after=_retry_after(resp))
+    if status == 404 or code == "not_found":
+        raise NotFoundError(detail, code=code or "not_found", status=status)
+    if status in (400, 422) or code == "bad_request":
+        raise BadRequestError(detail, code=code or "bad_request", status=status)
+    if status == 503 or code == "disabled":
+        raise DisabledError(detail, code=code or "disabled", status=status)
+    raise ImhoError(detail, code=code, status=status)
+
+
+def _rpc_result(resp: httpx.Response) -> Dict[str, Any]:
+    if resp.status_code == 429:
+        raise RateLimitError(resp.text[:500], retry_after=_retry_after(resp))
+    if resp.status_code >= 400:
+        raise ImhoError(resp.text[:500] or resp.reason_phrase, status=resp.status_code)
+    data = resp.json()
+    if "error" in data:
+        err = data["error"] or {}
+        raise BadRequestError(
+            str(err.get("message", "JSON-RPC error")),
+            code=str(err.get("code")),
+            status=resp.status_code,
+        )
+    return cast(Dict[str, Any], data.get("result") or {})
+
+
+def _tool_payload(result: Mapping[str, Any]) -> Dict[str, Any]:
+    if result.get("isError"):
+        text = " ".join(
+            str(c.get("text", "")) for c in result.get("content") or [] if isinstance(c, Mapping)
+        ).strip()
+        match = _RATE_TEXT.search(text)
+        if match:
+            raise RateLimitError(text, retry_after=float(match.group(1)))
+        if text.startswith("No ") and "matched" in text:
+            raise NotFoundError(text, code="not_found")
+        if "switched off" in text:
+            raise DisabledError(text, code="disabled")
+        raise ToolError(text or "Tool call failed")
+    structured = result.get("structuredContent")
+    if isinstance(structured, dict):
+        return structured
+    # Fall back to the JSON text block.
+    for block in result.get("content") or []:
+        if isinstance(block, Mapping) and block.get("type") == "text":
+            try:
+                parsed = json.loads(block.get("text", ""))
+            except ValueError:
+                continue
+            if isinstance(parsed, dict):
+                return parsed
+    return {"content": list(result.get("content") or [])}
+
+
+def _client_kwargs(
+    base_url: str, timeout: float, headers: Optional[Mapping[str, str]]
+) -> Dict[str, Any]:
+    merged = {"User-Agent": USER_AGENT}
+    if headers:
+        merged.update(headers)
+    return {"base_url": base_url.rstrip("/"), "timeout": timeout, "headers": merged}
+
+
+def _timeout(timeout: Optional[float]) -> Any:
+    return timeout if timeout is not None else httpx.USE_CLIENT_DEFAULT
+
+
+# ── sync client ────────────────────────────────────────────────────────────
+
+
+class ImhoClient:
+    """Blocking client.
+
+    >>> from imho import ImhoClient
+    >>> with ImhoClient() as imho:
+    ...     picks = imho.games_like("Hollow Knight", n=5, coop=True)
+    """
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        headers: Optional[Mapping[str, str]] = None,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.Client(**_client_kwargs(base_url, timeout, headers))
+
+    def __enter__(self) -> ImhoClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._http.close()
+
+    def _get(self, request: Request) -> Dict[str, Any]:
+        path, params = request
+        return _raise_for_rest(self._http.get(path, params=tuple(params)))
+
+    def games_like(
+        self,
+        game: str,
+        *,
+        n: int = 10,
+        lang: Lang = "en",
+        free: bool = False,
+        coop: Coop = False,
+        steam_deck: Optional[SteamDeck] = None,
+    ) -> GamesLikeResult:
+        """Steam games similar to ``game`` (name, appid or Steam URL), ranked."""
+        req = _games_like_request(game, n, lang, free, coop, steam_deck)
+        return cast(GamesLikeResult, self._get(req))
+
+    def recommend(
+        self,
+        seeds: Sequence[str],
+        *,
+        n: int = 10,
+        lang: Lang = "en",
+        liked: Sequence[str] = (),
+        disliked: Sequence[str] = (),
+        preferences: Optional[str] = None,
+        free: bool = False,
+        coop: Coop = False,
+        steam_deck: Optional[SteamDeck] = None,
+        exclude: Sequence[Exclude] = (),
+        exclude_tags: Sequence[str] = (),
+        year_min: Optional[int] = None,
+        year_max: Optional[int] = None,
+        upcoming: bool = False,
+        popularity_bias: float = 0.0,
+    ) -> RecommendResult:
+        """Games for someone who likes 1-3 ``seeds``, with the full filter set.
+
+        ``preferences`` is free text ("cozy base building, no horror") read as
+        Steam tags. ``disliked`` games are never recommended.
+        """
+        req = _recommend_request(
+            seeds,
+            n=n,
+            lang=lang,
+            liked=liked,
+            disliked=disliked,
+            preferences=preferences,
+            free=free,
+            coop=coop,
+            steam_deck=steam_deck,
+            exclude=exclude,
+            exclude_tags=exclude_tags,
+            year_min=year_min,
+            year_max=year_max,
+            upcoming=upcoming,
+            popularity_bias=popularity_bias,
+        )
+        return cast(RecommendResult, self._get(req))
+
+    def game_facts(self, game: str, *, lang: Lang = "en") -> GameFactsResult:
+        """Public facts about one Steam game."""
+        return cast(GameFactsResult, self._get(_game_facts_request(game, lang)))
+
+    def trending(
+        self, *, kind: TrendingKind = "rising", n: int = 10, lang: Lang = "en"
+    ) -> TrendingResult:
+        """Steam games trending now: ``rising`` (established) or ``breakouts`` (new)."""
+        return cast(TrendingResult, self._get(_trending_request(kind, n, lang)))
+
+    def new_releases(
+        self, *, upcoming: bool = False, coop: bool = False, n: int = 10, lang: Lang = "en"
+    ) -> NewReleasesResult:
+        """Well-rated Steam releases of the last 30 days, or dated upcoming games."""
+        req = _new_releases_request(upcoming, coop, n, lang)
+        return cast(NewReleasesResult, self._get(req))
+
+    def search_games(self, query: str, *, n: int = 5) -> SearchResult:
+        """Steam games by title (typos, partial and Russian names are fine)."""
+        return cast(SearchResult, self._get(_search_request(query, n)))
+
+    def find_game_by_description(
+        self,
+        description: str,
+        *,
+        lang: Lang = "en",
+        platform: Optional[Platform] = None,
+        year_min: Optional[int] = None,
+        year_max: Optional[int] = None,
+        perspective: Optional[Perspective] = None,
+    ) -> FindGameResult:
+        """Identify a game from what someone remembers about it.
+
+        Slow (runs a language model) and limited to 3 calls a minute and 20 a
+        day per IP. Use it only when the title is unknown.
+        """
+        args = _find_args(description, lang, platform, year_min, year_max, perspective)
+        payload = self.call_tool("find_game_by_description", args, timeout=FIND_TIMEOUT)
+        return cast(FindGameResult, payload)
+
+    def call_tool(
+        self,
+        name: str,
+        arguments: Optional[Mapping[str, Any]] = None,
+        *,
+        timeout: Optional[float] = None,
+    ) -> Dict[str, Any]:
+        """Call any MCP tool by name and return its structured result."""
+        resp = self._http.post(
+            "/mcp",
+            json=_tool_call(name, arguments),
+            headers=_MCP_HEADERS,
+            timeout=_timeout(timeout),
+        )
+        return _tool_payload(_rpc_result(resp))
+
+    def list_tools(self) -> List[Dict[str, Any]]:
+        """The MCP server's tool definitions (name, description, input schema)."""
+        resp = self._http.post("/mcp", json=_rpc("tools/list"), headers=_MCP_HEADERS)
+        return cast(List[Dict[str, Any]], _rpc_result(resp).get("tools", []))
+
+
+# ── async client ───────────────────────────────────────────────────────────
+
+
+class AsyncImhoClient:
+    """Async client with the same methods as :class:`ImhoClient`.
+
+    >>> async with AsyncImhoClient() as imho:
+    ...     facts = await imho.game_facts("Hades")
+    """
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        headers: Optional[Mapping[str, str]] = None,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.AsyncClient(**_client_kwargs(base_url, timeout, headers))
+
+    async def __aenter__(self) -> AsyncImhoClient:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._http.aclose()
+
+    async def _get(self, request: Request) -> Dict[str, Any]:
+        path, params = request
+        return _raise_for_rest(await self._http.get(path, params=tuple(params)))
+
+    async def games_like(
+        self,
+        game: str,
+        *,
+        n: int = 10,
+        lang: Lang = "en",
+        free: bool = False,
+        coop: Coop = False,
+        steam_deck: Optional[SteamDeck] = None,
+    ) -> GamesLikeResult:
+        req = _games_like_request(game, n, lang, free, coop, steam_deck)
+        return cast(GamesLikeResult, await self._get(req))
+
+    async def recommend(
+        self,
+        seeds: Sequence[str],
+        *,
+        n: int = 10,
+        lang: Lang = "en",
+        liked: Sequence[str] = (),
+        disliked: Sequence[str] = (),
+        preferences: Optional[str] = None,
+        free: bool = False,
+        coop: Coop = False,
+        steam_deck: Optional[SteamDeck] = None,
+        exclude: Sequence[Exclude] = (),
+        exclude_tags: Sequence[str] = (),
+        year_min: Optional[int] = None,
+        year_max: Optional[int] = None,
+        upcoming: bool = False,
+        popularity_bias: float = 0.0,
+    ) -> RecommendResult:
+        req = _recommend_request(
+            seeds,
+            n=n,
+            lang=lang,
+            liked=liked,
+            disliked=disliked,
+            preferences=preferences,
+            free=free,
+            coop=coop,
+            steam_deck=steam_deck,
+            exclude=exclude,
+            exclude_tags=exclude_tags,
+            year_min=year_min,
+            year_max=year_max,
+            upcoming=upcoming,
+            popularity_bias=popularity_bias,
+        )
+        return cast(RecommendResult, await self._get(req))
+
+    async def game_facts(self, game: str, *, lang: Lang = "en") -> GameFactsResult:
+        return cast(GameFactsResult, await self._get(_game_facts_request(game, lang)))
+
+    async def trending(
+        self, *, kind: TrendingKind = "rising", n: int = 10, lang: Lang = "en"
+    ) -> TrendingResult:
+        return cast(TrendingResult, await self._get(_trending_request(kind, n, lang)))
+
+    async def new_releases(
+        self, *, upcoming: bool = False, coop: bool = False, n: int = 10, lang: Lang = "en"
+    ) -> NewReleasesResult:
+        req = _new_releases_request(upcoming, coop, n, lang)
+        return cast(NewReleasesResult, await self._get(req))
+
+    async def search_games(self, query: str, *, n: int = 5) -> SearchResult:
+        return cast(SearchResult, await self._get(_search_request(query, n)))
+
+    async def find_game_by_description(
+        self,
+        description: str,
+        *,
+        lang: Lang = "en",
+        platform: Optional[Platform] = None,
+        year_min: Optional[int] = None,
+        year_max: Optional[int] = None,
+        perspective: Optional[Perspective] = None,
+    ) -> FindGameResult:
+        args = _find_args(description, lang, platform, year_min, year_max, perspective)
+        payload = await self.call_tool("find_game_by_description", args, timeout=FIND_TIMEOUT)
+        return cast(FindGameResult, payload)
+
+    async def call_tool(
+        self,
+        name: str,
+        arguments: Optional[Mapping[str, Any]] = None,
+        *,
+        timeout: Optional[float] = None,
+    ) -> Dict[str, Any]:
+        resp = await self._http.post(
+            "/mcp",
+            json=_tool_call(name, arguments),
+            headers=_MCP_HEADERS,
+            timeout=_timeout(timeout),
+        )
+        return _tool_payload(_rpc_result(resp))
+
+    async def list_tools(self) -> List[Dict[str, Any]]:
+        resp = await self._http.post("/mcp", json=_rpc("tools/list"), headers=_MCP_HEADERS)
+        return cast(List[Dict[str, Any]], _rpc_result(resp).get("tools", []))
+
+
+__all__ = ["DEFAULT_BASE_URL", "USER_AGENT", "AsyncImhoClient", "ImhoClient"]

imho/errors.py

@@ -0,0 +1,66 @@
+"""Exceptions raised by the imho client."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class ImhoError(Exception):
+    """Any error answer from imho.run.
+
+    ``code`` is the API's error code when it sent one (``not_found``,
+    ``bad_request``, ``rate_limited``, ``disabled``), ``status`` the HTTP status.
+    """
+
+    def __init__(
+        self,
+        detail: str,
+        *,
+        code: Optional[str] = None,
+        status: Optional[int] = None,
+    ) -> None:
+        super().__init__(detail)
+        self.detail = detail
+        self.code = code
+        self.status = status
+
+
+class NotFoundError(ImhoError):
+    """No game matched the query."""
+
+
+class BadRequestError(ImhoError):
+    """The request was rejected (a parameter out of range, an empty query)."""
+
+
+class RateLimitError(ImhoError):
+    """Too many requests. ``retry_after`` is in seconds when the server sent it."""
+
+    def __init__(
+        self,
+        detail: str,
+        *,
+        code: Optional[str] = "rate_limited",
+        status: Optional[int] = 429,
+        retry_after: Optional[float] = None,
+    ) -> None:
+        super().__init__(detail, code=code, status=status)
+        self.retry_after = retry_after
+
+
+class DisabledError(ImhoError):
+    """The API is switched off on the server side for now."""
+
+
+class ToolError(ImhoError):
+    """An MCP tool call returned ``isError: true``."""
+
+
+__all__ = [
+    "BadRequestError",
+    "DisabledError",
+    "ImhoError",
+    "NotFoundError",
+    "RateLimitError",
+    "ToolError",
+]

imho/types.py

@@ -0,0 +1,297 @@
+"""Response shapes of the imho.run agent API.
+
+These are ``TypedDict``s: the client returns the decoded JSON as plain dicts,
+and the types only describe them. Keys can be added on the server side at any
+time, so code should ignore keys it does not know. Every key here is optional
+(``total=False``) because some are omitted when the value is unknown.
+"""
+
+from __future__ import annotations
+
+from typing import List, Literal, Optional, TypedDict
+
+Lang = Literal["en", "ru"]
+SteamDeck = Literal["verified", "playable"]
+CoopMode = Literal["online", "local"]
+Platform = Literal["pc", "playstation", "xbox", "nintendo", "sega", "mobile", "browser", "arcade"]
+Perspective = Literal["first", "third", "top_down", "side"]
+Exclude = Literal["pvp", "microtransactions", "hard", "grind", "early_access", "vr_only"]
+TrendingKind = Literal["rising", "breakouts"]
+
+
+class Price(TypedDict, total=False):
+    is_free: bool
+    amount: Optional[float]
+    currency: Optional[str]
+    text: str
+
+
+class Reviews(TypedDict, total=False):
+    total: int
+    positive_pct: Optional[int]
+
+
+class GameRef(TypedDict, total=False):
+    appid: int
+    name: str
+    url: str
+    steam_url: str
+
+
+class Filters(TypedDict, total=False):
+    free: bool
+    coop: bool
+    coop_mode: Optional[CoopMode]
+    deck: Optional[SteamDeck]
+
+
+class Recommendation(TypedDict, total=False):
+    rank: int
+    appid: int
+    name: str
+    url: str
+    steam_url: str
+    why: str
+    year: Optional[int]
+    price: Price
+    steam_deck: Optional[str]
+    reviews: Reviews
+    genres: List[str]
+
+
+class GamesLikeResult(TypedDict, total=False):
+    query: str
+    source: str
+    attribution: str
+    seed: GameRef
+    other_matches: List[GameRef]
+    lang: Lang
+    filters: Filters
+    list_url: str
+    results: List[Recommendation]
+    generated_at: str
+
+
+class FactsSummary(TypedDict, total=False):
+    tagline: Optional[str]
+    difficulty: Optional[str]
+    length: Optional[str]
+    session_shape: Optional[str]
+    co_op: Optional[str]
+    hooks: List[str]
+    dealbreakers: List[str]
+    language: str
+
+
+class CoopViaMod(TypedDict, total=False):
+    mod_name: str
+    mod_url: str
+    scope: str
+    scope_text: str
+    max_players: Optional[int]
+    maturity: str
+    status: str
+    last_checked: str
+    official_coop_is_summon_only: bool
+    note: str
+    note_lang: str
+    caveats: List[str]
+
+
+class GameFacts(TypedDict, total=False):
+    appid: int
+    name: str
+    url: str
+    similar_url: str
+    steam_url: str
+    year: Optional[int]
+    release_date: Optional[str]
+    coming_soon: bool
+    developers: List[str]
+    genres: List[str]
+    tags: List[str]
+    price: Price
+    steam_deck: Optional[str]
+    reviews: Reviews
+    description: Optional[str]
+    description_lang: str
+    summary: FactsSummary
+    coop_via_mod: CoopViaMod
+
+
+class GameFactsResult(TypedDict, total=False):
+    query: str
+    source: str
+    attribution: str
+    lang: Lang
+    game: GameFacts
+    other_matches: List[GameRef]
+    generated_at: str
+
+
+class FoundGame(TypedDict, total=False):
+    rank: int
+    name: str
+    year: Optional[int]
+    platforms: List[str]
+    why: str
+    summary: Optional[str]
+    steam_appid: Optional[int]
+    url: Optional[str]
+    steam_url: Optional[str]
+    igdb_url: Optional[str]
+
+
+class FindGameResult(TypedDict, total=False):
+    source: str
+    attribution: str
+    lang: Lang
+    confidence: str
+    results: List[FoundGame]
+    tool_url: str
+    find_game_url: str
+
+
+# ── recommend ──────────────────────────────────────────────────────────────
+
+
+class RecommendQuery(TypedDict, total=False):
+    seeds: List[str]
+    preferences: Optional[str]
+    liked: List[str]
+    disliked: List[str]
+
+
+class RecommendFilters(TypedDict, total=False):
+    free: bool
+    coop: bool
+    coop_mode: Optional[str]
+    deck: Optional[SteamDeck]
+    exclude: List[str]
+    exclude_tags: List[str]
+    year_min: Optional[int]
+    year_max: Optional[int]
+    popularity_bias: float
+
+
+class PreferencesRead(TypedDict, total=False):
+    """How the ``preferences`` text was read."""
+
+    applied: bool
+    prefer_tags: List[str]
+    avoid_tags: List[str]
+    filters: List[str]
+    unmatched: List[str]
+    suggestions: List[str]
+
+
+class RecommendPick(Recommendation, total=False):
+    similar_to: Optional[int]
+    """Appid of the seed this pick is closest to."""
+
+
+class RecommendResult(TypedDict, total=False):
+    query: RecommendQuery
+    source: str
+    attribution: str
+    seeds: List[GameRef]
+    lang: Lang
+    filters: RecommendFilters
+    preferred_tags: List[str]
+    tool_url: str
+    results: List[RecommendPick]
+    preferences_applied: bool
+    preferences: PreferencesRead
+    ignored: List[str]
+    generated_at: str
+
+
+# ── trending / new releases / search ───────────────────────────────────────
+
+
+class ListPick(TypedDict, total=False):
+    rank: int
+    appid: int
+    name: str
+    url: str
+    steam_url: str
+    year: Optional[int]
+    price: Price
+    steam_deck: str
+    reviews: Optional[Reviews]
+    genres: List[str]
+    reviews_week: int
+    """trending: Steam reviews in the last 7 days."""
+    reviews_growth_pct: int
+    """trending: weekly reviews vs the game's own 3-week baseline, in %."""
+    release_date: str
+    """new_releases: Steam release date."""
+
+
+class TrendingResult(TypedDict, total=False):
+    source: str
+    attribution: str
+    lang: Lang
+    kind: TrendingKind
+    status: Literal["ready", "collecting"]
+    """``collecting``: the lists are not ready yet and ``results`` is empty."""
+    updated_at: Optional[str]
+    page_url: str
+    results: List[ListPick]
+
+
+class NewReleasesResult(TypedDict, total=False):
+    source: str
+    attribution: str
+    lang: Lang
+    kind: Literal["released", "upcoming"]
+    coop: bool
+    page_url: str
+    results: List[ListPick]
+
+
+class SearchHit(TypedDict, total=False):
+    appid: int
+    name: str
+    year: Optional[int]
+    url: str
+    steam_url: str
+
+
+class SearchResult(TypedDict, total=False):
+    query: str
+    source: str
+    results: List[SearchHit]
+
+
+__all__ = [
+    "CoopMode",
+    "CoopViaMod",
+    "Exclude",
+    "FactsSummary",
+    "Filters",
+    "FindGameResult",
+    "FoundGame",
+    "GameFacts",
+    "GameFactsResult",
+    "GameRef",
+    "GamesLikeResult",
+    "Lang",
+    "ListPick",
+    "NewReleasesResult",
+    "Perspective",
+    "Platform",
+    "PreferencesRead",
+    "Price",
+    "RecommendFilters",
+    "RecommendPick",
+    "RecommendQuery",
+    "RecommendResult",
+    "Recommendation",
+    "Reviews",
+    "SearchHit",
+    "SearchResult",
+    "SteamDeck",
+    "TrendingKind",
+    "TrendingResult",
+]

imho-0.2.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+imho/__init__.py,sha256=MPGnnGDKnmVSb56nQncZ_N-J-BHfXNiWUoDxbCXwZkQ,730
+imho/_version.py,sha256=Zn1KFblwuFHiDRdRAiRnDBRkbPttWh44jKa5zG2ov0E,22
+imho/client.py,sha256=37hKD_X-EbclTycFFsSYyF16l9rt0sP-gFQ8jnZfnkI,20487
+imho/errors.py,sha256=tSsuXV_1u9YI-iEgw0PmMgBOs7ONAwm9-rH3a4Rn3Dw,1538
+imho/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+imho/types.py,sha256=kKor2N05AXU6JzMa9L9yPqLOhBbNEC5r5Z5bf9Eu0gY,6810
+imho-0.2.0.dist-info/METADATA,sha256=qmEGEjyLOk25Rw5YE7jHv0x4nJIbN23n-t8m2lDKbms,7655
+imho-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+imho-0.2.0.dist-info/licenses/LICENSE,sha256=eQmqpNCbdOc_FxVecIZ-Com-kCqK1FjkXA3DfCUffnE,1065
+imho-0.2.0.dist-info/RECORD,,

imho-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

imho-0.2.0.dist-info/licenses/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.