fastspec 0.0.1__py3-none-any.whl

fastspec/__init__.py

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

fastspec/_modidx.py

@@ -0,0 +1,97 @@
+# Autogenerated by nbdev
+
+d = { 'settings': { 'branch': 'main',
+                'doc_baseurl': '/fastspec',
+                'doc_host': 'https://AnswerDotAI.github.io',
+                'git_url': 'https://github.com/AnswerDotAI/fastspec',
+                'lib_path': 'fastspec'},
+  'syms': { 'fastspec.errors': { 'fastspec.errors.APIError': ('errors.html#apierror', 'fastspec/errors.py'),
+                                 'fastspec.errors.APIError.__init__': ('errors.html#apierror.__init__', 'fastspec/errors.py'),
+                                 'fastspec.errors.APIError.__str__': ('errors.html#apierror.__str__', 'fastspec/errors.py'),
+                                 'fastspec.errors.APIError.with_context': ('errors.html#apierror.with_context', 'fastspec/errors.py'),
+                                 'fastspec.errors.FastSpecError': ('errors.html#fastspecerror', 'fastspec/errors.py'),
+                                 'fastspec.errors.ProtocolError': ('errors.html#protocolerror', 'fastspec/errors.py'),
+                                 'fastspec.errors.SpecError': ('errors.html#specerror', 'fastspec/errors.py'),
+                                 'fastspec.errors._parse_sse_error_event': ('errors.html#_parse_sse_error_event', 'fastspec/errors.py'),
+                                 'fastspec.errors._req_id': ('errors.html#_req_id', 'fastspec/errors.py'),
+                                 'fastspec.errors._retryable': ('errors.html#_retryable', 'fastspec/errors.py'),
+                                 'fastspec.errors._to_text': ('errors.html#_to_text', 'fastspec/errors.py'),
+                                 'fastspec.errors.api_error_from_event': ('errors.html#api_error_from_event', 'fastspec/errors.py'),
+                                 'fastspec.errors.httpx.HTTPStatusError.api_error': ( 'errors.html#httpx.httpstatuserror.api_error',
+                                                                                      'fastspec/errors.py'),
+                                 'fastspec.errors.httpx.Response.error': ('errors.html#httpx.response.error', 'fastspec/errors.py')},
+            'fastspec.oapi': { 'fastspec.oapi.OpFunc': ('oapi.html#opfunc', 'fastspec/oapi.py'),
+                               'fastspec.oapi.OpFunc.__call__': ('oapi.html#opfunc.__call__', 'fastspec/oapi.py'),
+                               'fastspec.oapi.OpFunc.__init__': ('oapi.html#opfunc.__init__', 'fastspec/oapi.py'),
+                               'fastspec.oapi.OpFunc._bind': ('oapi.html#opfunc._bind', 'fastspec/oapi.py'),
+                               'fastspec.oapi.OpFunc._raise_with_context': ('oapi.html#opfunc._raise_with_context', 'fastspec/oapi.py'),
+                               'fastspec.oapi.OpFunc._repr_markdown_': ('oapi.html#opfunc._repr_markdown_', 'fastspec/oapi.py'),
+                               'fastspec.oapi.OpFunc._request': ('oapi.html#opfunc._request', 'fastspec/oapi.py'),
+                               'fastspec.oapi.OpFunc._split': ('oapi.html#opfunc._split', 'fastspec/oapi.py'),
+                               'fastspec.oapi.OpFunc._stream': ('oapi.html#opfunc._stream', 'fastspec/oapi.py'),
+                               'fastspec.oapi.OpGroup': ('oapi.html#opgroup', 'fastspec/oapi.py'),
+                               'fastspec.oapi.OpGroup.__init__': ('oapi.html#opgroup.__init__', 'fastspec/oapi.py'),
+                               'fastspec.oapi.OpGroup._repr_markdown_': ('oapi.html#opgroup._repr_markdown_', 'fastspec/oapi.py'),
+                               'fastspec.oapi.OpenAPIClient': ('oapi.html#openapiclient', 'fastspec/oapi.py'),
+                               'fastspec.oapi.OpenAPIClient.__init__': ('oapi.html#openapiclient.__init__', 'fastspec/oapi.py'),
+                               'fastspec.oapi._build_groups': ('oapi.html#_build_groups', 'fastspec/oapi.py'),
+                               'fastspec.oapi._join_url': ('oapi.html#_join_url', 'fastspec/oapi.py'),
+                               'fastspec.oapi._mk_param': ('oapi.html#_mk_param', 'fastspec/oapi.py'),
+                               'fastspec.oapi._op_line': ('oapi.html#_op_line', 'fastspec/oapi.py'),
+                               'fastspec.oapi._op_summary': ('oapi.html#_op_summary', 'fastspec/oapi.py'),
+                               'fastspec.oapi._path': ('oapi.html#_path', 'fastspec/oapi.py'),
+                               'fastspec.oapi._sort_key': ('oapi.html#_sort_key', 'fastspec/oapi.py'),
+                               'fastspec.oapi.mk_doc': ('oapi.html#mk_doc', 'fastspec/oapi.py'),
+                               'fastspec.oapi.mk_sig': ('oapi.html#mk_sig', 'fastspec/oapi.py'),
+                               'fastspec.oapi.sanitized_params': ('oapi.html#sanitized_params', 'fastspec/oapi.py')},
+            'fastspec.spec': { 'fastspec.spec.OpSpec': ('spec.html#opspec', 'fastspec/spec.py'),
+                               'fastspec.spec.OpSpec.__post_init__': ('spec.html#opspec.__post_init__', 'fastspec/spec.py'),
+                               'fastspec.spec.OpSpec._repr_markdown_': ('spec.html#opspec._repr_markdown_', 'fastspec/spec.py'),
+                               'fastspec.spec.OpSpec.mk_doc': ('spec.html#opspec.mk_doc', 'fastspec/spec.py'),
+                               'fastspec.spec.SpecParser': ('spec.html#specparser', 'fastspec/spec.py'),
+                               'fastspec.spec.SpecParser.__init__': ('spec.html#specparser.__init__', 'fastspec/spec.py'),
+                               'fastspec.spec.SpecParser.__repr__': ('spec.html#specparser.__repr__', 'fastspec/spec.py'),
+                               'fastspec.spec.SpecParser.from_discovery': ('spec.html#specparser.from_discovery', 'fastspec/spec.py'),
+                               'fastspec.spec.SpecParser.from_openapi': ('spec.html#specparser.from_openapi', 'fastspec/spec.py'),
+                               'fastspec.spec._body_params': ('spec.html#_body_params', 'fastspec/spec.py'),
+                               'fastspec.spec._clean_desc': ('spec.html#_clean_desc', 'fastspec/spec.py'),
+                               'fastspec.spec._collect_params': ('spec.html#_collect_params', 'fastspec/spec.py'),
+                               'fastspec.spec._discovery_body_params': ('spec.html#_discovery_body_params', 'fastspec/spec.py'),
+                               'fastspec.spec._discovery_collect_params': ('spec.html#_discovery_collect_params', 'fastspec/spec.py'),
+                               'fastspec.spec._first_url': ('spec.html#_first_url', 'fastspec/spec.py'),
+                               'fastspec.spec._group_name': ('spec.html#_group_name', 'fastspec/spec.py'),
+                               'fastspec.spec._op_docs_url': ('spec.html#_op_docs_url', 'fastspec/spec.py'),
+                               'fastspec.spec._path_params': ('spec.html#_path_params', 'fastspec/spec.py'),
+                               'fastspec.spec._prop_default': ('spec.html#_prop_default', 'fastspec/spec.py'),
+                               'fastspec.spec._prop_desc': ('spec.html#_prop_desc', 'fastspec/spec.py'),
+                               'fastspec.spec._resolve_obj': ('spec.html#_resolve_obj', 'fastspec/spec.py'),
+                               'fastspec.spec._resolve_ref': ('spec.html#_resolve_ref', 'fastspec/spec.py'),
+                               'fastspec.spec._schema_props_required': ('spec.html#_schema_props_required', 'fastspec/spec.py'),
+                               'fastspec.spec._schema_py_type': ('spec.html#_schema_py_type', 'fastspec/spec.py'),
+                               'fastspec.spec.discovery_to_ops': ('spec.html#discovery_to_ops', 'fastspec/spec.py'),
+                               'fastspec.spec.openapi_to_ops': ('spec.html#openapi_to_ops', 'fastspec/spec.py'),
+                               'fastspec.spec.snake': ('spec.html#snake', 'fastspec/spec.py')},
+            'fastspec.sse': { 'fastspec.sse.SSEvent': ('sse.html#ssevent', 'fastspec/sse.py'),
+                              'fastspec.sse.aiter_sse': ('sse.html#aiter_sse', 'fastspec/sse.py')},
+            'fastspec.transport': { 'fastspec.transport.AsyncTransport': ('transport.html#asynctransport', 'fastspec/transport.py'),
+                                    'fastspec.transport.AsyncTransport.__init__': ( 'transport.html#asynctransport.__init__',
+                                                                                    'fastspec/transport.py'),
+                                    'fastspec.transport.AsyncTransport._decode': ( 'transport.html#asynctransport._decode',
+                                                                                   'fastspec/transport.py'),
+                                    'fastspec.transport.AsyncTransport._headers': ( 'transport.html#asynctransport._headers',
+                                                                                    'fastspec/transport.py'),
+                                    'fastspec.transport.AsyncTransport._request_headers': ( 'transport.html#asynctransport._request_headers',
+                                                                                            'fastspec/transport.py'),
+                                    'fastspec.transport.AsyncTransport.aclose': ( 'transport.html#asynctransport.aclose',
+                                                                                  'fastspec/transport.py'),
+                                    'fastspec.transport.AsyncTransport.request': ( 'transport.html#asynctransport.request',
+                                                                                   'fastspec/transport.py'),
+                                    'fastspec.transport.AsyncTransport.stream': ( 'transport.html#asynctransport.stream',
+                                                                                  'fastspec/transport.py')},
+            'fastspec.types': { 'fastspec.types.Completion': ('types.html#completion', 'fastspec/types.py'),
+                                'fastspec.types.Delta': ('types.html#delta', 'fastspec/types.py'),
+                                'fastspec.types.Msg': ('types.html#msg', 'fastspec/types.py'),
+                                'fastspec.types.Part': ('types.html#part', 'fastspec/types.py'),
+                                'fastspec.types.RequestOptions': ('types.html#requestoptions', 'fastspec/types.py'),
+                                'fastspec.types.ToolCall': ('types.html#toolcall', 'fastspec/types.py'),
+                                'fastspec.types.Usage': ('types.html#usage', 'fastspec/types.py')}}}

fastspec/errors.py

@@ -0,0 +1,166 @@
+"""fastspec errors."""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/00_errors.ipynb.
+
+# %% auto #0
+__all__ = ['FastSpecError', 'SpecError', 'ProtocolError', 'APIError', 'api_error_from_event']
+
+# %% ../nbs/00_errors.ipynb #b4e7c7ed
+from fastcore.utils import *
+import json, httpx
+
+# %% ../nbs/00_errors.ipynb #87c600ab
+class FastSpecError(Exception):
+    "Base fastspec error."
+
+# %% ../nbs/00_errors.ipynb #3832e5fa
+class SpecError(FastSpecError):
+    "Raised when an OpenAPI spec cannot be parsed as expected."
+
+# %% ../nbs/00_errors.ipynb #be534d1b
+class ProtocolError(FastSpecError):
+    "Raised when provider payloads do not match expected protocol shape."
+
+# %% ../nbs/00_errors.ipynb #73881e99
+def _to_text(v):
+    "Best-effort stringify helper."
+    if v is None: return ""
+    if isinstance(v, str): return v
+    try: return json.dumps(v, ensure_ascii=False)
+    except Exception: return str(v)
+
+# %% ../nbs/00_errors.ipynb #2d51e006
+def _retryable(status_code, error_type, code, message):
+    "Classify transient/retryable API failures."
+    if isinstance(status_code, int) and (status_code >= 500 or status_code in (408, 409, 425, 429)): return True
+    t = str(error_type or "").lower()
+    c = str(code or "").lower()
+    m = (message or "").lower()
+    hints = ("server_error", "internal", "overload", "rate_limit", "timeout", "unavailable", "temporar")
+    if any(h in t for h in hints): return True
+    if any(h in c for h in hints): return True
+    if any(h in m for h in ("try again", "server error", "temporar", "timeout", "overloaded", "unavailable")): return True
+    return False
+
+# %% ../nbs/00_errors.ipynb #9c1cdf65
+def _req_id(headers):
+    "Extract provider request id header when available."
+    if headers is None: return ""
+    for k in ("x-request-id", "request-id", "anthropic-request-id", "x-goog-request-id"):
+        v = headers.get(k)
+        if v: return str(v)
+    return ""
+
+# %% ../nbs/00_errors.ipynb #fdf25eba
+@patch
+def error(self: httpx.Response):
+    "Parse common HTTP API error shapes to (message, error_type, code, raw)."
+    try: raw = self.json()
+    except Exception: raw = self.text
+
+    msg, et, code, status = "", "", None, None
+    if isinstance(raw, dict):
+        err = raw.get("error")
+        if isinstance(err, dict):
+            msg = str(err.get("message") or raw.get("message") or raw.get("detail") or "")
+            status = err.get("status", raw.get("status"))
+            et = str(err.get("type") or status or raw.get("type") or "")
+            code = err.get("code", raw.get("code"))
+        elif err is not None:
+            msg = _to_text(err)
+            status = raw.get("status")
+            et = str(raw.get("type") or status or "")
+            code = raw.get("code")
+        else:
+            msg = str(raw.get("message") or raw.get("detail") or raw.get("error_description") or "")
+            status = raw.get("status")
+            et = str(raw.get("type") or status or "")
+            code = raw.get("code")
+        if not msg: msg = _to_text(raw)
+    else:
+        msg = _to_text(raw)
+    # Prefer semantic provider codes (e.g. Gemini `status`) over numeric HTTP-like codes.
+    if (code is None or isinstance(code, int)) and isinstance(status, str) and status:
+        code = status
+    if code in (None, "") and isinstance(et, str) and et:
+        code = et
+    return AttrDict(message=msg, type=et, code=code, raw=raw)
+
+# %% ../nbs/00_errors.ipynb #24ed43ac
+def _parse_sse_error_event(event):
+    "Parse common SSE `error` event shapes to (message, error_type, code, raw)."
+    raw = event
+    e = event.get("error") if isinstance(event, dict) and isinstance(event.get("error"), dict) else (
+        event if isinstance(event, dict) else {"message": _to_text(event)})
+    msg = str(e.get("message") or e.get("detail") or _to_text(e))
+    et = str(e.get("type") or e.get("status") or "")
+    code = e.get("code")
+    if (code is None or isinstance(code, int)) and isinstance(et, str) and et: code = et
+    return AttrDict(message=msg, type=et, code=code, raw=raw)
+
+# %% ../nbs/00_errors.ipynb #0de145da
+class APIError(FastSpecError):
+    "Structured API error with optional context."
+    def __init__(self, message: str, *, provider: str = "", model: str = "", endpoint: str = "",
+        status_code= None, error_type: str = "", code = None, request_id: str = "",
+        retryable = None, raw = None):
+        self.message = message or "API request failed"
+        self.provider = provider or ""
+        self.model = model or ""
+        self.endpoint = endpoint or ""
+        self.status_code = status_code
+        self.error_type = error_type or ""
+        self.code = code
+        self.request_id = request_id or ""
+        self.retryable = _retryable(status_code, self.error_type, self.code, self.message) if retryable is None else bool(retryable)
+        self.raw = raw
+        super().__init__(self.__str__())
+
+    def with_context(self, *, provider: str = "", model: str = "", endpoint: str = "") -> "APIError":
+        "Return a copy with missing context fields filled."
+        return APIError(
+            self.message,
+            provider=self.provider or provider,
+            model=self.model or model,
+            endpoint=self.endpoint or endpoint,
+            status_code=self.status_code,
+            error_type=self.error_type,
+            code=self.code,
+            request_id=self.request_id,
+            retryable=self.retryable,
+            raw=self.raw,
+        )
+
+    def __str__(self):
+        fields = ['message', 'provider', 'model', 'endpoint', 'status_code', 'error_type', 'code', 'request_id', 'retryable']
+        parts = [f"{f}={getattr(self, f)!r}" for f in fields if getattr(self, f) not in (None, "", False)]
+        return f"APIError({', '.join(parts)})"
+
+    __repr__ = __str__
+
+# %% ../nbs/00_errors.ipynb #83d2dc0c
+@patch
+def api_error(self:httpx.HTTPStatusError, *, provider: str = "", model: str = "", endpoint: str = ""):
+    "Build APIError from httpx HTTPStatusError."
+    resp = self.response
+    err = resp.error()
+    if not endpoint and resp.request is not None:
+        endpoint = f"{resp.request.method.upper()} {resp.request.url.path}"
+    return APIError(
+        err.message,
+        provider=provider,
+        model=model,
+        endpoint=endpoint,
+        status_code=resp.status_code,
+        error_type=err.type,
+        code=err.code,
+        request_id=_req_id(resp.headers),
+        raw=err.raw,
+    )
+
+# %% ../nbs/00_errors.ipynb #e6e2cc84
+def api_error_from_event(event, *, provider: str = "", model: str = "", endpoint: str = ""):
+    "Build APIError from provider SSE/event-level error payload."
+    parsed = _parse_sse_error_event(event)
+    return APIError(parsed.message, provider=provider, model=model, endpoint=endpoint, error_type=parsed.type, code=parsed.code, raw=parsed.raw)
+

fastspec/oapi.py

@@ -0,0 +1,225 @@
+"""Dynamic OpenAPI operation client (async)."""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/04_oapi.ipynb.
+
+# %% auto #0
+__all__ = ['sanitized_params', 'mk_sig', 'mk_doc', 'OpFunc', 'OpGroup', 'OpenAPIClient']
+
+# %% ../nbs/04_oapi.ipynb #632a2010
+import httpx,json,keyword
+from inspect import Parameter, Signature
+from urllib.parse import urlparse, urljoin, quote
+from fastcore.utils import *
+from fastcore.meta import delegates
+
+from .errors import APIError
+from .spec import OpSpec, SpecParser, snake
+from .transport import AsyncTransport
+
+# %% ../nbs/04_oapi.ipynb #68bf64d1
+def _mk_param(name, required, anno=None, default=None):
+    "Create a function signature parameter."
+    anno = Parameter.empty if anno is None else anno
+    if default is None: default = Parameter.empty if required else UNSET
+    return Parameter(name, kind=Parameter.POSITIONAL_OR_KEYWORD, default=default, annotation=anno)
+
+# %% ../nbs/04_oapi.ipynb #6d0f4f6c
+def _sort_key(o):
+    if o.default is Parameter.empty: return 0
+    if o.default is UNSET: return 1
+    return 2
+
+def sanitized_params(op):
+    "Mapping from original param names to valid Python identifiers."
+    res = {}
+    for p in op.route_params + op.query_params + op.body_params + op.file_params:
+        name = snake(re.sub(r'\W', '_', p).strip('_'))
+        if keyword.iskeyword(name): name += '_'
+        res[p] = name
+    return res
+
+def mk_sig(op, sparams):
+    "Create a compact operation signature from an Opop."
+    params = []
+    for pname, sname in sparams.items():
+        params.append(_mk_param(sname, pname in op.required_params, op.param_types.get(pname), op.param_defaults.get(pname)))
+    return Signature(sorted(params, key=_sort_key))
+
+# %% ../nbs/04_oapi.ipynb #4d489284
+def _op_summary(op):
+    'Single line op summary with fallback and link rewriting'
+    s = re.sub(r"\s+", " ", str(op.summary or f"{op.verb} {op.path}")).strip() or f"{op.verb} {op.path}"
+    if not op.docs_url: return s
+    p = urlparse(op.docs_url)
+    base = f"{p.scheme}://{p.netloc}"
+    return re.sub(r"\]\((/[^)]+)\)", lambda m: f"]({urljoin(base, m[1].strip())})", s)
+
+# %% ../nbs/04_oapi.ipynb #48cf5a69
+def _op_line(op, sig):
+    head = f"{'.'.join(snake(g) for g in listify(op.group))}.{op.name}"
+    if op.docs_url: head = f"[{head}]({op.docs_url})" 
+    s = f"({', '.join(sig.parameters)})"
+    summ = _op_summary(op)
+    return f"{head}{s}: *{summ}*"
+
+# %% ../nbs/04_oapi.ipynb #3fb52bb7
+def mk_doc(op, sig, sparams):
+    "Render operation docstring with summary, docs URL, and parameter hints."
+    lines = [_op_summary(op)]
+    if op.docs_url: lines.append(f"\nDocs: {op.docs_url}")
+    if sig.parameters:
+        lines.append("\nParameters:")
+        req = set(op.required_params or [])
+        # Reverse map: sparamsitized → original, for looking up docs/required
+        rsparams = {v:k for k,v in sparams.items()}
+        for nm,p in sig.parameters.items():
+            orig = rsparams.get(nm, nm)
+            r = "required" if orig in req else "optional"
+            ann = '' if p.annotation is Parameter.empty else p.annotation.__name__
+            desc = (op.param_docs or {}).get(orig, "")
+            lines.append(f"- {nm} ({ann}, {r}){': ' + desc if desc else ''}")
+    return "\n".join(lines)
+
+# %% ../nbs/04_oapi.ipynb #6b2f1057
+class OpFunc:
+    def __init__(self, op_spec, client, base_url):
+        store_attr()
+        self.sparams       = sanitized_params(op_spec)
+        self.__signature__ = mk_sig(op_spec, self.sparams)
+        self.__doc__       = mk_doc(op_spec, self.__signature__, self.sparams)
+        self.__name__      = op_spec.name
+        self.name          = op_spec.name
+        self.group         = op_spec.group
+        self.path          = op_spec.path
+        self.verb          = op_spec.verb
+        self.route_params  = op_spec.route_params
+        self.query_params  = op_spec.query_params
+        self.body_params   = op_spec.body_params
+        self.file_params   = op_spec.file_params
+        self.summary       = op_spec.summary
+        self.docs_url      = op_spec.docs_url
+
+    def _repr_markdown_(self): return self.__doc__
+    __repr__ = basic_repr()
+
+# %% ../nbs/04_oapi.ipynb #6e381df4
+@patch
+def _bind(self:OpFunc, args, kwargs):
+    'Prepare kwargs from args and kwargs'
+    flds = [o for o in self.__signature__.parameters if o not in kwargs]
+    for a,b in zip(args, flds): kwargs[b] = a
+    return kwargs
+
+# %% ../nbs/04_oapi.ipynb #9327d89c
+@patch
+def _split(self:OpFunc, kwargs):
+    "Split kwargs into route/query/body/files + control kwargs."
+    stream = kwargs.get("stream", False)
+    headers = kwargs.pop("_headers", {})
+    # Map sanitized names back to originals
+    rsparams = {v:k for k,v in self.sparams.items()}
+
+    route, query, body, files = {}, {}, {}, {}
+    for k,v in kwargs.items():
+        if v is UNSET: continue
+        orig = rsparams.get(k, k)
+        if   orig in self.route_params: route[orig] = v
+        elif orig in self.file_params:  files[orig] = v
+        elif orig in self.query_params: query[orig] = v
+        elif orig in self.body_params:  body[orig] = v
+
+    query.update(kwargs.pop("_query", {}))
+    body.update(kwargs.pop("_body", {}))
+    if self.verb in ("GET", "DELETE", "HEAD", "OPTIONS") and not body: body = None
+    return stream, headers, route, query, body, files
+
+# %% ../nbs/04_oapi.ipynb #7b604f4e
+def _path(path, route_params={}):
+    "Apply route params to path template."
+    if not route_params: return path
+    for k,v in route_params.items():
+        s = str(v)
+        safe = "/" if "/" in s else ""
+        path = path.replace("{" + k + "}", quote(s, safe=safe))
+        path = path.replace("{+" + k + "}", quote(str(v), safe="/"))
+    return re.sub(r"\{\+([^}]+)\}", lambda m: "{" + m.group(1) + "}", path)
+
+# %% ../nbs/04_oapi.ipynb #5f8425a6
+def _join_url(base, path):
+    "Join base URL and path, ensuring correct slash handling."
+    return urljoin(base.rstrip("/") + "/", path.lstrip("/"))
+
+# %% ../nbs/04_oapi.ipynb #ca48c44b
+@patch
+def _raise_with_context(self:OpFunc, exc: Exception, *, endpoint: str, route: Optional[dict], query: Optional[dict], body: Optional[dict]):
+    "Raise APIError with operation context for dynamic op calls."
+    provider,model,ep = '','',''
+    # TODO: Make APIError generic, users can modify/subclass it include additional info like model,provider etc..
+    if isinstance(exc, httpx.HTTPStatusError): raise exc.api_error(provider=provider, model=model) from exc
+    raise exc
+
+# %% ../nbs/04_oapi.ipynb #c7c96f87
+@patch
+@delegates(AsyncTransport.request) # files, raw
+async def _request(self:OpFunc, url, *, headers=None, query=None, body=None, route=None, **kwargs):
+    "Execute an HTTP request and return decoded response."
+    try: return await self.client.request(self.verb, url, headers=headers, params=query, json_data=body, **kwargs)
+    except Exception as e: self._raise_with_context(e, endpoint='', route=route, query=query, body=body)
+
+@patch
+@delegates(AsyncTransport.stream) # files, raw
+async def _stream(self:OpFunc, url, *, headers=None, query=None, body=None, route=None, **kwargs):
+    "Execute an SSE request yielding parsed JSON events."
+    try:
+        async for ev in self.client.stream(self.verb, url, headers=headers, params=query, json_data=body, **kwargs): yield ev
+    except Exception as e: self._raise_with_context(e, endpoint='', route=route, query=query, body=body)
+
+# %% ../nbs/04_oapi.ipynb #3b0399ad
+@patch
+async def __call__(self:OpFunc, *args, **kwargs):
+    stream, headers, route, query, body, files = self._split(self._bind(args, kwargs))
+    url = _join_url(self.base_url, _path(self.path, route_params=route))
+    if files: kw = dict(body=None, files=files, data=body or None)
+    else:     kw = dict(body=body)
+    if stream: return self._stream(url, headers=headers, query=query, route=route, **kw)
+    return     await self._request(url, headers=headers, query=query, route=route, **kw)
+
+# %% ../nbs/04_oapi.ipynb #99464917
+class OpGroup:
+    "Simple namespace for grouped operations."
+    def __init__(self, name: str, ops: Iterable[OpFunc]):
+        self.name,self.ops = name,list(ops)
+        repr_md = []
+        for op in self.ops: 
+            setattr(self, op.name, op)
+            if hasattr(op, '__signature__'): repr_md.append(f"- {_op_line(op, op.__signature__)}")
+        self.__doc__ = "\n".join(repr_md)
+    
+    def _repr_markdown_(self): return self.__doc__
+
+# %% ../nbs/04_oapi.ipynb #51975775
+def _build_groups(ops:List[OpFunc]):
+    "Build nested op group tree from ops."
+    root = {}
+    for op in ops:
+        g = [snake(p) for p in listify(op.group)]
+        node = root
+        for part in g[:-1]: node = node.setdefault(part, {})
+        node.setdefault(g[-1], {}).setdefault('_ops', []).append(op)
+
+    def _mk(name, d):
+        grp = OpGroup(name, d.pop('_ops', []))
+        for k,v in d.items(): setattr(grp, k, _mk(k, v))
+        return grp
+
+    return {k: _mk(k, v) for k,v in root.items()}
+
+# %% ../nbs/04_oapi.ipynb #d4ff9dd9
+class OpenAPIClient:
+    "Async client built from OpenAPI operation metadata."
+    def __init__(self, spec, *, headers=None, timeout=60.0):
+        self.transport = AsyncTransport(timeout=timeout, base_headers=headers)
+        self.ops = [OpFunc(o, self.transport, spec.base_url) for o in spec.ops]
+        self.func_dict = {f"{o.path}:{o.verb.upper()}": o for o in self.ops}
+        self.groups = _build_groups(self.ops)
+        for k,v in self.groups.items(): setattr(self, k, v)