hoshimi 0.1.0__py3-none-any.whl

hoshimi/__init__.py

@@ -0,0 +1,15 @@
+"""Hoshimi: an OpenAI-compatible gateway over free model stations (Cline, TRAE, ZCode, ...).
+
+To embed the API and the web UI in another application:
+
+    from hoshimi.api.app import create_app
+    from hoshimi.core.context import build_services
+
+    app = create_app(build_services())
+"""
+
+from hoshimi._exports import __dir__ as __dir__
+from hoshimi._exports import __getattr__ as __getattr__
+from hoshimi.version import VERSION as VERSION
+
+__all__ = ["VERSION", "Services", "build_services", "create_app"]

hoshimi/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m hoshimi``."""
+
+from hoshimi.cli.app import main
+
+if __name__ == "__main__":
+    main()

hoshimi/_exports.py

@@ -0,0 +1,22 @@
+"""Resolve the embedding API lazily so basic commands avoid importing FastAPI."""
+
+from typing import Any
+
+
+def __getattr__(name: str) -> Any:
+    """Load an embedding API export only when the caller requests it."""
+    if name in ("Services", "build_services"):
+        from hoshimi.core import context
+
+        return getattr(context, name)
+    if name == "create_app":
+        from hoshimi.api.app import create_app
+
+        return create_app
+    raise AttributeError(f"module 'hoshimi' has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    from hoshimi import __all__
+
+    return sorted(__all__)

hoshimi/api/app.py

@@ -0,0 +1,98 @@
+"""``create_app(services)``: the FastAPI app with routers, the security layer and the web UI."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from starlette.middleware.gzip import GZipMiddleware
+
+from hoshimi.api.errors import install_error_handlers
+from hoshimi.api.routers import app_info, catalog, chat, classification, credits, health, login, messages, models, playground, probe, providers, refresh, settings, stats
+from hoshimi.api.security import SecurityMiddleware
+from hoshimi.api.static import SPAStaticFiles, web_dist_dir
+from hoshimi.core.context import Services
+from hoshimi.core.errors import ValidationError
+from hoshimi.core.security import build_policy, validate_security_settings
+from hoshimi.version import VERSION
+
+logger = logging.getLogger(__name__)
+
+INFERENCE_ROUTES = (chat, models, classification, messages)
+
+
+def normalize_prefix(prefix: str | None) -> str:
+    """``/gateway/`` and ``gateway`` both become ``/gateway``; nothing becomes ``""``."""
+    cleaned = (prefix or "").strip().strip("/")
+    return f"/{cleaned}" if cleaned else ""
+
+
+def create_app(
+    services: Services,
+    bound_host: str | None = None,
+    bound_port: int | None = None,
+    extra_hosts: set[str] | None = None,
+    serve_ui: bool = True,
+    api_prefix: str | None = None,
+) -> FastAPI:
+    """Build the application.
+
+    ``api_prefix`` moves everything this package serves — the API and the web UI — under one
+    path, so a host application can mount it beside its own routes without a clash. The web UI
+    needs no change: it derives its base URL from the URL its own script was loaded from.
+    """
+    problem = validate_security_settings(services.settings)
+    if problem:
+        raise ValidationError(problem)
+
+    prefix = normalize_prefix(api_prefix)
+
+    @asynccontextmanager
+    async def lifespan(_app: FastAPI) -> AsyncGenerator[None, None]:
+        # The renewal timer is off when the operator set server.auto_refresh=false
+        # or built Services without a refresher (tests, embedders).
+        if services.refresher is not None and services.settings.auto_refresh:
+            services.refresher.start()
+        if services.credits is not None and services.settings.auto_checkin:
+            services.credits.start()
+        try:
+            yield
+        finally:
+            services.close()
+
+    app = FastAPI(title="Hoshimi", version=VERSION, lifespan=lifespan, docs_url=f"{prefix}/docs", redoc_url=None, openapi_url=f"{prefix}/openapi.json")
+    app.state.services = services
+    app.state.bound_port = bound_port
+    app.state.api_prefix = prefix
+    install_error_handlers(app)
+
+    # Management API under /api; inference protocols share /v1.
+    app.include_router(health.router, prefix=prefix)
+    for module in (app_info, settings, providers, catalog, probe, stats, refresh, credits, login, playground):
+        app.include_router(module.router, prefix=f"{prefix}/api")
+    for module in INFERENCE_ROUTES:
+        app.include_router(module.router, prefix=prefix)
+
+    origins = services.settings.allow_origins
+    if origins:
+        app.add_middleware(CORSMiddleware, allow_origins=origins, allow_methods=["*"], allow_headers=["*"], allow_credentials=True)
+    # Chat deltas are small; long JSON payloads compress well.
+    app.add_middleware(GZipMiddleware, minimum_size=4096)
+    app.add_middleware(
+        SecurityMiddleware,
+        policy=lambda: build_policy(services.settings),
+        bound_host=lambda: bound_host or services.settings.host,
+        extra_hosts=extra_hosts,
+        prefix=prefix,
+    )
+
+    # Registered last, so it only receives paths nothing else matched.
+    dist = web_dist_dir()
+    if serve_ui and (dist / "index.html").is_file():
+        app.mount(f"{prefix}/", SPAStaticFiles(directory=dist, html=True), name="ui")
+    elif serve_ui:
+        logger.warning("No web UI build found at %s; serving the API only", dist)
+    return app

hoshimi/api/deps.py

@@ -0,0 +1,14 @@
+"""FastAPI dependencies. Services come from ``app.state`` rather than a global locator."""
+
+from typing import Annotated
+
+from fastapi import Depends, Request
+
+from hoshimi.core.context import Services
+
+
+def get_services(request: Request) -> Services:
+    return request.app.state.services
+
+
+ServicesDep = Annotated[Services, Depends(get_services)]

hoshimi/api/errors.py

@@ -0,0 +1,115 @@
+"""Map domain exceptions onto the endpoint's JSON error shape.
+
+``/v1/*`` speaks OpenAI's error envelope (``{"error": {"message", "type", "code"}}``) because
+that is what OpenAI clients parse. Messages uses Anthropic's envelope;
+management routes answer Hoshimi's ``{code, message, detail}``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.exception_handlers import request_validation_exception_handler
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from pydantic import Field
+
+from hoshimi.api.paths import route_path
+from hoshimi.core.errors import HoshimiError, ModelNotFoundError, UpstreamError, ValidationError
+from hoshimi.core.record import Record
+
+# Domain code -> the ``type`` OpenAI clients expect.
+OPENAI_ERROR_TYPES = {
+    "not_found": "invalid_request_error",
+    "model_not_found": "invalid_request_error",
+    "invalid_input": "invalid_request_error",
+    "conflict": "invalid_request_error",
+    "upstream_error": "upstream_error",
+    "quota_exceeded": "upstream_error",
+    "auth_failed": "upstream_error",
+    "internal_error": "server_error",
+}
+
+
+class ErrorResponse(Record):
+    code: str
+    message: str
+    detail: dict[str, Any] = Field(default_factory=dict)
+
+
+class AnthropicErrorDetail(Record):
+    type: str
+    message: str
+
+
+class AnthropicErrorResponse(Record):
+    type: str
+    error: AnthropicErrorDetail
+
+
+ANTHROPIC_ERROR_RESPONSES: dict[int | str, dict[str, Any]] = {status: {"model": AnthropicErrorResponse} for status in (400, 401, 403, 404, 429, 500, 502, 503, "default")}
+
+
+def openai_error(message: str, error_type: str, code: str | None = None) -> dict[str, Any]:
+    return {"error": {"message": message, "type": error_type, "code": code}}
+
+
+def is_messages_path(path: str) -> bool:
+    return path.rstrip("/").endswith(("/v1/messages", "/v1/messages/count_tokens"))
+
+
+def anthropic_error(message: str, status: int) -> dict[str, Any]:
+    kind = {
+        400: "invalid_request_error",
+        401: "authentication_error",
+        403: "permission_error",
+        404: "not_found_error",
+        413: "request_too_large",
+        429: "rate_limit_error",
+        529: "overloaded_error",
+    }.get(status, "api_error")
+    return {"type": "error", "error": {"type": kind, "message": message}}
+
+
+def error_type_for(exc: HoshimiError) -> str:
+    if isinstance(exc, UpstreamError):
+        return "upstream_error"
+    if isinstance(exc, (ModelNotFoundError, ValidationError)):
+        return "invalid_request_error"
+    return OPENAI_ERROR_TYPES.get(exc.code, "server_error")
+
+
+def error_response(status: int, code: str, message: str, detail: dict[str, Any] | None = None, headers: dict[str, str] | None = None) -> JSONResponse:
+    return JSONResponse(status_code=status, content={"code": code, "message": message, "detail": detail or {}}, headers=headers)
+
+
+async def _domain_error(request: Request, exc: Exception) -> JSONResponse:
+    assert isinstance(exc, HoshimiError)
+    if is_messages_path(route_path(request.scope)):
+        return JSONResponse(status_code=exc.http_status, content=anthropic_error(exc.message, exc.http_status))
+    if route_path(request.scope).startswith("/v1/"):
+        payload = openai_error(exc.message, error_type_for(exc), code=exc.code if exc.code != "internal_error" else None)
+        return JSONResponse(status_code=exc.http_status, content=payload)
+    return error_response(exc.http_status, exc.code, exc.message, exc.detail)
+
+
+def install_error_handlers(app: FastAPI) -> None:
+    app.add_exception_handler(HoshimiError, _domain_error)
+    app.add_exception_handler(RequestValidationError, _validation_error)
+
+
+async def _validation_error(request: Request, exc: Exception) -> JSONResponse:
+    assert isinstance(exc, RequestValidationError)
+    if is_messages_path(route_path(request.scope)):
+        return JSONResponse(status_code=400, content=anthropic_error("Invalid Messages request body.", 400))
+    return await request_validation_exception_handler(request, exc)
+
+
+# Declared on routes so the generated client knows the error shape.
+ERROR_RESPONSES: dict[int | str, dict[str, Any]] = {
+    400: {"model": ErrorResponse},
+    404: {"model": ErrorResponse},
+    403: {"model": ErrorResponse},
+    409: {"model": ErrorResponse},
+}

hoshimi/api/inference.py

@@ -0,0 +1,48 @@
+"""Shared model selection and accounting for the public inference protocols."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Iterator
+from typing import Any
+
+from hoshimi.core.context import Services
+from hoshimi.core.effort import requested_level, resolve_level
+from hoshimi.core.errors import ValidationError
+
+
+def prepare_request(services: Services, body: dict[str, Any]) -> tuple[str, dict[str, Any]]:
+    model = body.get("model")
+    if not isinstance(model, str) or not model.strip():
+        model = services.settings.default_model or services.registry.default_model or ""
+    if not model:
+        raise ValidationError("Missing 'model' field.")
+    body = dict(body)
+    body["model"] = model
+    body.setdefault("prompt_cache_key", f"hoshimi-{int(time.time())}")
+    return model, body
+
+
+def tracked_chunks(
+    services: Services,
+    model: str,
+    body: dict[str, Any],
+    *,
+    origin: str,
+) -> Iterator[dict[str, Any]]:
+    """The upstream stream with this call's usage, latency and outcome recorded.
+
+    The turn starts here so a routing failure still counts: a request the
+    gateway refused is a request it answered. Effort is the rung the wire
+    carries: a caller who named none sends none, and the sample must not
+    claim a level the body never had.
+    """
+    level = requested_level(body)
+    effort = (resolve_level(level, services.registry.spec(model)) or "") if level else ""
+    turn = services.stats.turn(model, effort=effort, origin=origin)
+    try:
+        upstream = services.registry.stream(model, body)
+    except BaseException:
+        turn.fail()
+        raise
+    return turn.wrap(upstream)

hoshimi/api/paths.py

@@ -0,0 +1,33 @@
+"""Deployment paths shared by mounted apps, authentication and Socket.IO."""
+
+from urllib.parse import urlsplit
+
+from starlette import _utils
+from starlette.requests import Request
+from starlette.types import Scope
+
+
+def route_path(scope: Scope) -> str:
+    """Older Starlette strips mount prefixes; newer versions leave that to the router."""
+    resolve = getattr(_utils, "get_route_path", None)
+    return resolve(scope) if resolve is not None else scope.get("path", "")
+
+
+def public_prefix(request: Request) -> str:
+    base = getattr(request.app.state, "public_base_url", None)
+    if base:
+        return urlsplit(base).path.rstrip("/")
+    root = request.scope.get("root_path", "").rstrip("/")
+    return root + (getattr(request.app.state, "api_prefix", "") or "")
+
+
+def validate_public_base_url(value: str | None) -> str | None:
+    """Only the host application may supply this URL; never derive it from forwarded headers."""
+    if value is None:
+        return None
+    url = urlsplit(value)
+    if url.scheme not in ("http", "https") or not url.hostname or url.username is not None or url.password is not None or url.query or url.fragment:
+        raise ValueError("public_base_url must be an absolute HTTP(S) URL without credentials, query or fragment")
+    if any(c.isspace() for c in value) or "\\" in value:
+        raise ValueError("public_base_url contains invalid characters")
+    return value.rstrip("/")

hoshimi/api/routers/app_info.py

@@ -0,0 +1,64 @@
+"""App version, health and what the interface needs to know about this server."""
+
+from fastapi import APIRouter, Request
+
+from hoshimi.api.deps import ServicesDep
+from hoshimi.core.net.ports import is_loopback
+from hoshimi.core.providers import real_account_count
+from hoshimi.core.record import Record
+from hoshimi.version import VERSION
+
+router = APIRouter(prefix="/v1/app", tags=["app"])
+
+
+class AppVersion(Record):
+    version: str
+
+
+class Health(Record):
+    status: str
+    auth_required: bool
+
+
+class AppMeta(Record):
+    version: str
+    auth_required: bool
+    model_api_key_configured: bool
+    local: bool
+    """True when this request comes from the server's own machine."""
+    api_prefix: str
+    data_dir: str
+    config_path: str | None
+    default_model: str | None
+    providers: int
+    accounts: int
+
+
+@router.get("/version", operation_id="get_app_version")
+def get_version() -> AppVersion:
+    return AppVersion(version=VERSION)
+
+
+@router.get("/health", operation_id="get_health")
+def get_health(services: ServicesDep) -> Health:
+    return Health(status="ok", auth_required=bool(services.settings.access_token))
+
+
+@router.get("/meta", operation_id="get_app_meta")
+def get_meta(request: Request, services: ServicesDep) -> AppMeta:
+    client = request.client.host if request.client else ""
+    accounts = sum(
+        real_account_count(provider) for provider in services.registry.providers.values()
+    )
+    return AppMeta(
+        version=VERSION,
+        auth_required=bool(services.settings.access_token),
+        model_api_key_configured=bool(services.settings.model_api_key),
+        local=bool(client) and (is_loopback(client) or client == "testclient"),
+        api_prefix=getattr(request.app.state, "api_prefix", "") or "",
+        data_dir=str(services.data_dir),
+        config_path=str(services.config_path) if services.config_path else None,
+        default_model=services.settings.default_model,
+        providers=len(services.registry.providers),
+        accounts=accounts,
+    )

hoshimi/api/routers/catalog.py

@@ -0,0 +1,197 @@
+"""Model capability catalogue for the web UI: what each id can do."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import AsyncIterator, Iterable
+from typing import Literal
+
+from fastapi import APIRouter
+from fastapi.responses import StreamingResponse
+from pydantic import Field
+
+from hoshimi.api.deps import ServicesDep
+from hoshimi.api.routers.probe import ProbeState
+from hoshimi.core.catalog import ModelSpec
+from hoshimi.core.effort import LEVELS, efforts_for
+from hoshimi.core.record import Record
+
+router = APIRouter(prefix="/v1", tags=["models"])
+CATALOG_TIMEOUT_SECONDS = 20.0
+
+
+class EffortOption(Record):
+    id: str
+    name: str
+    description: str = ""
+    is_default: bool = False
+    tokens: int | None = None
+
+
+class ModelSpecObject(Record):
+    id: str
+    provider: str
+    name: str
+    wire: str = "chat"
+    vision: bool = False
+    reasoning: bool = False
+    tools: bool | None = None
+    context_window: int = 0
+    max_output: int = 0
+    can_disable_thinking: bool = True
+    region_sensitive: bool = False
+    # Whether calling this id costs the account anything, per the station that
+    # serves it. None is "the station did not say", which is most ids at most
+    # stations — a price list is not something every gateway publishes.
+    free: bool | None = None
+    efforts: list[EffortOption]
+    effort_default: str | None = None
+    # The last availability verdict for this id, when a round has asked about it.
+    probe: ProbeState | None = None
+    # The gateway's own verdict: the station answered 404/410 for every
+    # account, so the id is banned for a while. Unlike `probe` this was not
+    # asked for — it is what serving this model taught the gateway.
+    unavailable: bool = False
+
+
+class ModelSpecList(Record):
+    levels: list[EffortOption]
+    data: list[ModelSpecObject]
+
+
+class CatalogProvider(Record):
+    id: str
+    status: Literal["loading", "ready", "failed", "timeout"]
+    data: list[ModelSpecObject]
+
+
+class CatalogEvent(Record):
+    type: Literal["snapshot", "provider", "done"]
+    levels: list[EffortOption] = Field(default_factory=list)
+    providers: list[CatalogProvider] = Field(default_factory=list)
+    provider: CatalogProvider | None = None
+
+
+class CatalogStreamResponse(StreamingResponse):
+    """Describe an individual event under the actual SSE media type in OpenAPI."""
+
+    media_type = "text/event-stream"
+
+
+def _probe_state(services, model: str) -> ProbeState | None:
+    row = services.probe.state_for(model)
+    return ProbeState(**row) if row else None
+
+
+@router.get("/models", operation_id="list_model_specs")
+def list_model_specs(services: ServicesDep) -> ModelSpecList:
+    """Every advertised model with its capability spec and effort menu.
+
+    `levels` is the free lane's token ladder (what a budget-driven model
+    offers); each model carries its own `efforts` when it has a menu.
+    """
+    return ModelSpecList(levels=_levels(), data=_model_objects(services, services.registry.catalog()))
+
+
+def _levels() -> list[EffortOption]:
+    return [
+        EffortOption(
+            id=level.id,
+            name=level.name,
+            description=level.hint,
+            is_default=level.id == "balanced",
+            tokens=None,
+        )
+        for level in LEVELS
+    ]
+
+
+def _model_objects(services, specs: Iterable[ModelSpec]) -> list[ModelSpecObject]:
+    data: list[ModelSpecObject] = []
+    for spec in specs:
+        options = efforts_for(spec) or []
+        data.append(
+            ModelSpecObject(
+                id=spec.id,
+                provider=spec.provider,
+                name=spec.name,
+                wire=spec.wire,
+                vision=spec.vision,
+                reasoning=spec.reasoning,
+                tools=spec.tools,
+                context_window=spec.context_window,
+                max_output=spec.max_output,
+                can_disable_thinking=spec.can_disable_thinking,
+                region_sensitive=spec.region_sensitive,
+                free=spec.free,
+                efforts=[EffortOption(**option) for option in options],
+                effort_default=next((option["id"] for option in options if option.get("is_default")), None),
+                probe=_probe_state(services, spec.id),
+                unavailable=services.registry.dead_models.is_dead(spec.provider, spec.id),
+            )
+        )
+    return data
+
+
+@router.get("/catalog/stream", operation_id="stream_catalog", response_class=CatalogStreamResponse,
+            responses={200: {"model": CatalogEvent}})
+def stream_catalog(services: ServicesDep) -> StreamingResponse:
+    """Send cached rows first, then each provider independently in completion order."""
+    return CatalogStreamResponse(catalog_events(services), headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"})
+
+
+async def catalog_events(services) -> AsyncIterator[str]:
+    discovery = services.registry.discovery
+    # Snapshot the actual objects: account edits must not mix old and new pools.
+    providers = services.registry.ordered_providers()
+
+    def row(pid, provider, status, specs=None):
+        try:
+            data = _model_objects(services, (specs if specs is not None else discovery.cached(provider).specs).values())
+        except Exception:  # noqa: BLE001 - malformed capabilities are isolated to their provider
+            return CatalogProvider(id=pid, status="failed", data=[])
+        return CatalogProvider(id=pid, status=status, data=data)
+
+    def event(value: CatalogEvent) -> str:
+        return f"data: {value.model_dump_json()}\n\n"
+
+    yield event(CatalogEvent(type="snapshot", levels=_levels(), providers=[row(pid, provider, "loading") for pid, provider in providers]))
+    pending = {asyncio.shield(asyncio.wrap_future(discovery.submit(provider))): (pid, provider) for pid, provider in providers}
+    deadline = time.monotonic() + CATALOG_TIMEOUT_SECONDS
+    try:
+        while pending:
+            done, _ = await asyncio.wait(pending, timeout=min(1.0, max(0, deadline - time.monotonic())), return_when=asyncio.FIRST_COMPLETED)
+            for future in done:
+                pid, provider = pending.pop(future)
+                result = future.result()
+                yield event(CatalogEvent(type="provider", provider=row(pid, provider, "failed" if result.failed else "ready", result.specs)))
+            if pending and time.monotonic() >= deadline:
+                for pid, provider in pending.values():
+                    yield event(CatalogEvent(type="provider", provider=row(pid, provider, "timeout")))
+                break
+            if pending and not done:
+                yield ": keep-alive\n\n"
+        yield event(CatalogEvent(type="done"))
+    finally:
+        # Shielded futures detach this subscriber without cancelling another
+        # browser's request or releasing a still-running synchronous worker.
+        for future in pending:
+            future.cancel()
+
+
+class UnavailableReset(Record):
+    cleared: int
+
+
+@router.post("/models/unavailable/reset", operation_id="reset_unavailable_models")
+def reset_unavailable_models(services: ServicesDep) -> UnavailableReset:
+    """Let every banned id back in.
+
+    The ban is the gateway remembering a refusal; this is the operator saying
+    the station has been fixed. A turn that gets an answer clears its own entry
+    anyway, so what this is really for is the entries nothing will retry: an id
+    no client asks for any more, or one that will 404 again the moment it is
+    tried and so can never be the request that clears it.
+    """
+    return UnavailableReset(cleared=services.registry.dead_models.clear_all())