wassitai 0.2.0__py3-none-any.whl

llm_parser/__init__.py

@@ -0,0 +1,116 @@
+"""Deprecated import alias for :mod:`wassitai`.
+
+The distribution was renamed ``llm_parser`` -> ``wassitai`` in 0.2. This package
+exists only so code written against the old name keeps working: it forwards
+every attribute *and* every submodule to :mod:`wassitai`, so both
+
+    from llm_parser import Client, parse
+    from llm_parser.llm_parser import LLMParser
+    from llm_parser.core import formatter
+
+resolve to the very same objects the ``wassitai.*`` paths give you -- not copies.
+It will be removed in 2.0; import from ``wassitai`` instead.
+
+Two deliberate limits, neither of which any caller in this repo relies on:
+``pkgutil.iter_modules(llm_parser.__path__)`` enumerates nothing (this directory
+really is empty), and ``python -m llm_parser.<mod>`` does not work. Use the
+``wassitai`` names for either.
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.abc
+import importlib.util
+import sys
+import warnings
+
+import wassitai as _wassitai
+
+_OLD = "llm_parser"
+_NEW = "wassitai"
+
+
+class _AliasLoader(importlib.abc.Loader):
+    """Loader that hands back an already-imported ``wassitai`` submodule."""
+
+    def __init__(self, real_name: str) -> None:
+        self._real_name = real_name
+        self._real_spec = None
+
+    def create_module(self, spec):
+        real = importlib.import_module(self._real_name)
+        self._real_spec = real.__spec__
+        return real
+
+    def exec_module(self, module) -> None:
+        # The real module was executed under its own name; re-running it would
+        # duplicate its state (registries, module-level singletons) under a
+        # second identity, which is exactly what this alias exists to prevent.
+        #
+        # Undo the one thing the import machinery did to it on the way here:
+        # `_init_module_attrs` overwrites `__spec__` unconditionally, so
+        # importing `llm_parser.core.formatter` would otherwise rename the live
+        # `wassitai.core.formatter` and blank its `submodule_search_locations` --
+        # breaking `reload()` and `importlib.resources` for callers that never
+        # touched the old name. The alias forwards one way only.
+        if self._real_spec is not None:
+            module.__spec__ = self._real_spec
+
+
+class _AliasFinder(importlib.abc.MetaPathFinder):
+    """Maps ``llm_parser.<sub>`` onto ``wassitai.<sub>``."""
+
+    # Duck-typed marker rather than isinstance: re-importing this module (tests
+    # do, to observe the warning) rebinds the class, so an isinstance check
+    # against the fresh class would miss the finder already on sys.meta_path and
+    # stack up a duplicate on every reload.
+    _wassitai_alias_finder = True
+
+    def find_spec(self, fullname, path=None, target=None):
+        if not fullname.startswith(_OLD + "."):
+            return None
+        real_name = _NEW + fullname[len(_OLD) :]
+        try:
+            real = importlib.import_module(real_name)
+        except ModuleNotFoundError as exc:
+            if exc.name != real_name:
+                # The module exists but its *own* imports failed -- a missing
+                # optional dependency, say. Swallowing that would report the
+                # alias as absent and destroy the real cause.
+                raise
+            return None  # genuinely absent: let the machinery raise as usual
+        return importlib.util.spec_from_loader(
+            fullname,
+            _AliasLoader(real_name),
+            is_package=hasattr(real, "__path__"),
+        )
+
+
+# Ahead of the path-based finder, which would otherwise fail to find submodules
+# that no longer live in this (now almost empty) directory.
+if not any(getattr(f, "_wassitai_alias_finder", False) for f in sys.meta_path):
+    sys.meta_path.insert(0, _AliasFinder())
+
+warnings.warn(
+    "The 'llm_parser' package was renamed to 'wassitai'; install it with "
+    "`pip install wassitai` and import `wassitai`. The 'llm_parser' alias will "
+    "be removed in 2.0.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+__all__ = list(_wassitai.__all__)
+
+
+def __getattr__(name: str):
+    # Delegated rather than star-imported so the alias never drifts from the
+    # real package's surface as that surface grows.
+    try:
+        return getattr(_wassitai, name)
+    except AttributeError:
+        raise AttributeError(f"module {_OLD!r} has no attribute {name!r}") from None
+
+
+def __dir__():
+    return sorted(set(__all__) | set(globals()))

wassitai/__init__.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from ._version import __version__
+from .client import Client, parse, try_parse
+from .config import Config
+from .errors import (
+    AuthenticationError,
+    ConfigurationError,
+    Diagnostic,
+    ExtractionError,
+    LLMParserError,
+    ParseError,
+    ProviderError,
+    ProviderHTTPError,
+    ProviderResponseError,
+    ProviderTimeoutError,
+    RateLimitError,
+    RepairError,
+    SchemaError,
+    SchemaValidationError,
+    UnknownProviderError,
+)
+from .render import render
+from .result import Result, Usage
+
+__all__ = [
+    "__version__",
+    "Client",
+    "parse",
+    "try_parse",
+    "Config",
+    "Result",
+    "Usage",
+    "render",
+    "Diagnostic",
+    "LLMParserError",
+    "ConfigurationError",
+    "UnknownProviderError",
+    "SchemaError",
+    "ProviderError",
+    "AuthenticationError",
+    "RateLimitError",
+    "ProviderTimeoutError",
+    "ProviderHTTPError",
+    "ProviderResponseError",
+    "ParseError",
+    "ExtractionError",
+    "RepairError",
+    "SchemaValidationError",
+]

wassitai/_version.py

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

wassitai/api/__init__.py

@@ -0,0 +1,3 @@
+from .app import app, create_app
+
+__all__ = ["app", "create_app"]

wassitai/api/app.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+
+from .._version import __version__
+from .errors import register_exception_handlers
+from .routes import router
+
+_STATIC = Path(__file__).parent / "static"
+
+
+class _RevalidatingStaticFiles(StaticFiles):
+    """Serve static assets with ``Cache-Control: no-cache``.
+
+    Plain ``StaticFiles`` sends no ``Cache-Control``, so browsers apply heuristic
+    freshness and can keep running a stale ``app.js``/``styles.css`` after an edit
+    without ever re-requesting it. ``no-cache`` means "cache, but always
+    revalidate": the browser issues a conditional request and gets a cheap 304
+    when nothing changed, or the fresh file the moment it does — so the playground
+    never boots old JS against a new page.
+    """
+
+    async def get_response(self, path: str, scope):  # type: ignore[override]
+        response = await super().get_response(path, scope)
+        response.headers.setdefault("Cache-Control", "no-cache")
+        return response
+
+
+def create_app() -> FastAPI:
+    app = FastAPI(
+        title="Wassitai API",
+        # One version for the whole distribution: a hardcoded literal here drifts
+        # from the package the moment either is bumped, and it is what `/docs` and
+        # the OpenAPI schema advertise.
+        version=__version__,
+        description="Structured generation & LLM-output parsing over HTTP.",
+    )
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+    app.include_router(router)
+    register_exception_handlers(app)
+
+    app.mount("/static", _RevalidatingStaticFiles(directory=str(_STATIC)), name="static")
+
+    @app.get("/", include_in_schema=False)
+    def index() -> FileResponse:
+        return FileResponse(str(_STATIC / "index.html"), headers={"Cache-Control": "no-cache"})
+
+    return app
+
+
+app = create_app()

wassitai/api/deps.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from wassitai import Client
+from wassitai.config import Config
+from wassitai.errors import AuthenticationError
+from wassitai.strategies.native import NativeStructuredOutputStrategy
+from wassitai.strategies.prompt_repair import PromptAndRepairStrategy
+from wassitai.strategies.tool_calling import ToolCallingStrategy
+
+_STRATEGIES = {
+    "native": NativeStructuredOutputStrategy,
+    "tool_calling": ToolCallingStrategy,
+    "prompt_repair": PromptAndRepairStrategy,
+}
+
+
+def resolve_key(provider: str, header_key: Optional[str]) -> str:
+    if header_key:
+        return header_key
+    env = os.getenv(f"{provider.upper()}_API_KEY")
+    if env:
+        return env
+    raise AuthenticationError(
+        f"No API key for '{provider}'. Supply the X-Provider-Key header "
+        f"or set {provider.upper()}_API_KEY on the server."
+    )
+
+
+def build_client(
+    provider: str,
+    key: str,
+    model: Optional[str] = None,
+    max_retries: Optional[int] = None,
+    strict: bool = False,
+    strategy: Optional[str] = None,
+) -> Client:
+    strat = _STRATEGIES[strategy]() if strategy in _STRATEGIES else None
+    cfg = Config(
+        strict=strict,
+        max_retries=1 if max_retries is None else max_retries,
+        strategy=strat,
+    )
+    kw = {"api_key": key, "config": cfg}
+    if model:
+        kw["model"] = model
+    return Client.from_provider(provider, **kw)

wassitai/api/errors.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from fastapi import Request
+from fastapi.responses import JSONResponse
+
+from wassitai.errors import (
+    AuthenticationError,
+    LLMParserError,
+    ParseError,
+    ProviderHTTPError,
+    ProviderResponseError,
+    ProviderTimeoutError,
+    RateLimitError,
+    SchemaError,
+    SchemaValidationError,
+    UnknownProviderError,
+)
+
+# Order matters: most specific first.
+_STATUS_TABLE = [
+    (AuthenticationError, 401),
+    (RateLimitError, 429),
+    (ProviderTimeoutError, 504),
+    (ProviderHTTPError, 502),
+    (ProviderResponseError, 502),
+    (UnknownProviderError, 400),
+    (SchemaError, 422),
+    (SchemaValidationError, 422),
+    (ParseError, 422),
+]
+
+
+def status_for(exc: LLMParserError) -> int:
+    for cls, code in _STATUS_TABLE:
+        if isinstance(exc, cls):
+            return code
+    return 500
+
+
+def error_body(exc: LLMParserError) -> dict:
+    body: dict = {"error": str(exc), "error_type": type(exc).__name__}
+    if isinstance(exc, ParseError):
+        body["diagnostics"] = [
+            {"stage": d.stage, "level": d.level, "message": d.message} for d in exc.diagnostics
+        ]
+        body["confidence"] = exc.confidence
+    return body
+
+
+def register_exception_handlers(app) -> None:
+    @app.exception_handler(LLMParserError)
+    async def _handle(request: Request, exc: LLMParserError):
+        return JSONResponse(status_code=status_for(exc), content=error_body(exc))

wassitai/api/models.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from typing import Any, Optional, Union
+
+from pydantic import BaseModel, Field
+
+
+class GenerateRequest(BaseModel):
+    provider: str
+    prompt: str
+    schema_: Union[dict, str] = Field(alias="schema")
+    model: Optional[str] = None
+    strict: bool = False
+    max_retries: Optional[int] = None
+    strategy: Optional[str] = None
+    render: Optional[str] = None  # "json" | "xml" | None (return the object)
+
+    model_config = {"populate_by_name": True}
+
+
+class ParseRequest(BaseModel):
+    text: str
+    schema_: Union[dict, str] = Field(alias="schema")
+    strict: bool = False
+    render: Optional[str] = None
+
+    model_config = {"populate_by_name": True}
+
+
+class GenerateResponse(BaseModel):
+    ok: bool
+    value: Any = None
+    rendered: Optional[str] = None
+    confidence: float = 1.0
+    diagnostics: list[dict[str, Any]] = []
+    usage: Optional[dict[str, int]] = None
+    error: Optional[str] = None
+
+
+class ProviderInfo(BaseModel):
+    name: str
+    capabilities: dict[str, Any]

wassitai/api/routes.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from fastapi import APIRouter, Header
+from pydantic import BaseModel
+
+from wassitai import __version__, try_parse
+from wassitai import render as render_obj
+from wassitai.providers import _PRESETS
+
+from .deps import build_client, resolve_key
+from .models import GenerateRequest, GenerateResponse, ParseRequest
+
+router = APIRouter()
+
+
+def _jsonable(value: object) -> object:
+    if isinstance(value, BaseModel):
+        return value.model_dump()
+    if isinstance(value, list):
+        return [_jsonable(v) for v in value]
+    return value
+
+
+def _diagnostics(result) -> list:
+    return [
+        {"stage": d.stage, "level": d.level, "message": d.message} for d in result.diagnostics
+    ]
+
+
+@router.get("/health")
+def health() -> dict:
+    return {"status": "ok", "version": __version__}
+
+
+@router.post("/v1/parse", response_model=GenerateResponse)
+def parse_route(req: ParseRequest) -> GenerateResponse:
+    result = try_parse(req.text, req.schema_, strict=req.strict)
+    value = result.unwrap()  # raises the typed error; mapped to a status by the handler
+    rendered = render_obj(value, fmt=req.render) if req.render else None
+    return GenerateResponse(
+        ok=True,
+        value=_jsonable(value),
+        rendered=rendered,
+        confidence=result.confidence,
+        diagnostics=_diagnostics(result),
+    )
+
+
+@router.post("/v1/generate", response_model=GenerateResponse)
+def generate_route(
+    req: GenerateRequest,
+    x_provider_key: Optional[str] = Header(default=None),
+) -> GenerateResponse:
+    key = resolve_key(req.provider, x_provider_key)  # -> 401 if missing
+    client = build_client(
+        req.provider,
+        key,
+        model=req.model,
+        max_retries=req.max_retries,
+        strict=req.strict,
+        strategy=req.strategy,
+    )
+    result = client.try_generate(req.prompt, schema=req.schema_)
+    value = result.unwrap()  # raises the typed error; mapped to a status by the handler
+    rendered = render_obj(value, fmt=req.render) if req.render else None
+    return GenerateResponse(
+        ok=True,
+        value=_jsonable(value),
+        rendered=rendered,
+        confidence=result.confidence,
+        diagnostics=_diagnostics(result),
+        usage=(result.usage.__dict__ if result.usage else None),
+    )
+
+
+@router.get("/v1/providers")
+def list_providers() -> dict:
+    return {
+        "providers": [
+            {
+                "name": name,
+                "capabilities": {
+                    "openai_compatible": True,
+                    "tool_calling": True,
+                    "json_mode": True,
+                },
+                "default_model": preset[1],
+            }
+            for name, preset in _PRESETS.items()
+        ]
+    }