From 8d255a4bb72fc764ca4724212277ad75365ff168 Mon Sep 17 00:00:00 2001 From: Pol Alvarez Date: Wed, 26 Aug 2026 15:13:19 +0200 Subject: [PATCH] added body examples to doc --- fastspec/_modidx.py | 1 + fastspec/oapi.py | 7 +- fastspec/spec.py | 14 ++-- nbs/03_spec.ipynb | 200 +++++++++++++++----------------------------- nbs/04_oapi.ipynb | 136 +++++++++++++++++++++++------- 5 files changed, 189 insertions(+), 169 deletions(-) diff --git a/fastspec/_modidx.py b/fastspec/_modidx.py index f19fa4c..bc66aae 100644 --- a/fastspec/_modidx.py +++ b/fastspec/_modidx.py @@ -87,6 +87,7 @@ 'fastspec.oapi.OpenAPIClient.full_docs': ('oapi.html#openapiclient.full_docs', 'fastspec/oapi.py'), 'fastspec.oapi.SyncOpFunc': ('oapi.html#syncopfunc', 'fastspec/oapi.py'), 'fastspec.oapi.SyncOpFunc.__call__': ('oapi.html#syncopfunc.__call__', 'fastspec/oapi.py'), + 'fastspec.oapi._examples_doc': ('oapi.html#_examples_doc', 'fastspec/oapi.py'), 'fastspec.oapi._join_url': ('oapi.html#_join_url', 'fastspec/oapi.py'), 'fastspec.oapi._path': ('oapi.html#_path', 'fastspec/oapi.py')}, 'fastspec.spec': { 'fastspec.spec.OpSpec': ('spec.html#opspec', 'fastspec/spec.py'), diff --git a/fastspec/oapi.py b/fastspec/oapi.py index 84b1835..1da9589 100644 --- a/fastspec/oapi.py +++ b/fastspec/oapi.py @@ -20,6 +20,11 @@ # %% ../nbs/04_oapi.ipynb #6b2f1057 +def _examples_doc(exs): + "Render body examples as an `Examples:` doc section, one fenced JSON block per example" + if not exs: return '' + return '\n\nExamples:' + ''.join(f"\n- {v.get('summary') or k}:\n```json\n{json.dumps(v['value'], indent=2)}\n```" for k,v in exs.items()) + class OpFunc: def __init__(self, op_spec, client, base_url, form_encoder=None, defaults=None): store_attr() @@ -40,7 +45,7 @@ def __init__(self, op_spec, client, base_url, form_encoder=None, defaults=None): self.required_params = op_spec.required_params self.param_docs = op_spec.param_docs self.__signature__ = mk_sig(op_spec, self.sparams, self.defaults) - self.__doc__ = mk_doc(self, self.__signature__, self.sparams) + self.__doc__ = mk_doc(self, self.__signature__, self.sparams) + _examples_doc(op_spec.body_examples) def _repr_markdown_(self): return self.__doc__ def __repr__(self): return f"{'.'.join(snake(g) for g in listify(self.group))}.{self.name}{self.__signature__}\n{self.docs_url}" diff --git a/fastspec/spec.py b/fastspec/spec.py index 3da978f..20aec8d 100644 --- a/fastspec/spec.py +++ b/fastspec/spec.py @@ -32,12 +32,13 @@ class OpSpec: param_types: Dict = field(default_factory=dict) param_defaults: Dict = field(default_factory=dict) param_docs: Dict = field(default_factory=dict) + body_examples: Dict = field(default_factory=dict) docs_url: str = "" def mk_doc(self): rows = [] for f,v in vars(self).items(): - if f not in ('param_types','param_defaults','param_docs'): rows.append(f'| `{f}` | {v} |') + if f not in ('param_types','param_defaults','param_docs','body_examples'): rows.append(f'| `{f}` | {v} |') md = f'| Field | Value |\n|---|---|\n' + '\n'.join(rows) all_params = self.route_params + self.query_params + self.body_params if all_params: @@ -197,10 +198,13 @@ def _body_params(op, spec): rb = _resolve_obj(op.get("requestBody", {}), spec) content = rb.get("content", {}) ct = first((ct for ct in ctypes if ct in content), None) - schema = content.get(ct, {}).get("schema") if ct else None + mt = content.get(ct) or {} + schema = mt.get("schema") + exs = mt.get("examples") or ({"default": {"value": mt["example"]}} if "example" in mt else {}) + bexs = {k: {"summary": r.get("summary",""), "value": r["value"]} for k,v in exs.items() if "value" in (r := _resolve_obj(v, spec))} if not schema: return AttrDict(body_params=[], file_params=[], required_params=set(), param_types={}, - param_docs={}, param_defaults={}, request_content_type=ct) + param_docs={}, param_defaults={}, request_content_type=ct, body_examples=bexs) props, req = _schema_props_required(schema, spec) fparams = [k for k,v in props.items() if _resolve_obj(v, spec).get("format") == "binary"] bparams = [k for k in props if k not in fparams] @@ -210,7 +214,7 @@ def _body_params(op, spec): # Params without a default or nullable type are required # req |= {k for k in props if k not in defaults} # too aggressive doesn't match when spec is incomplete return AttrDict(body_params=bparams, file_params=fparams, required_params=req, param_types=ptypes, - param_docs=pdocs, param_defaults=defaults, request_content_type=ct) + param_docs=pdocs, param_defaults=defaults, request_content_type=ct, body_examples=bexs) # %% ../nbs/03_spec.ipynb #9ab326f7 _pat_md_url = re.compile(r"\[[^\]]+\]\((https?://[^)\s]+)\)") @@ -268,7 +272,7 @@ def openapi_to_ops(spec, group_func=None): required_params=sorted(pdict.required_params | bpdict.required_params), param_types={k:v for k,v in merge(pdict.param_types, bpdict.param_types).items() if v}, param_defaults=_plain(merge(pdict.param_defaults, bpdict.param_defaults)), param_docs=merge(pdict.param_docs, bpdict.param_docs), - docs_url=_op_docs_url(op) or "")) + docs_url=_op_docs_url(op) or "", body_examples=_plain(bpdict.body_examples))) return res # %% ../nbs/03_spec.ipynb #78ea6617 diff --git a/nbs/03_spec.ipynb b/nbs/03_spec.ipynb index d78fda2..8e6cae6 100644 --- a/nbs/03_spec.ipynb +++ b/nbs/03_spec.ipynb @@ -309,8 +309,6 @@ { "data": { "text/markdown": [ - "
\n", - "\n", "- [gists.list](https://docs.github.com/rest/gists/gists#list-gists-for-the-authenticated-user)(since, per_page, page): *List gists for the authenticated user*\n", "- [gists.create](https://docs.github.com/rest/gists/gists#create-a-gist)(files, description, public): *Create a gist*\n", "- [gists.list_public](https://docs.github.com/rest/gists/gists#list-public-gists)(since, per_page, page): *List public gists*\n", @@ -330,9 +328,7 @@ "- [gists.star](https://docs.github.com/rest/gists/gists#star-a-gist)(gist_id): *Star a gist*\n", "- [gists.unstar](https://docs.github.com/rest/gists/gists#unstar-a-gist)(gist_id): *Unstar a gist*\n", "- [gists.get_revision](https://docs.github.com/rest/gists/gists#get-a-gist-revision)(gist_id, sha): *Get a gist revision*\n", - "- [gists.list_for_user](https://docs.github.com/rest/gists/gists#list-gists-for-a-user)(username, since, per_page, page): *List gists for a user*\n", - "\n", - "
" + "- [gists.list_for_user](https://docs.github.com/rest/gists/gists#list-gists-for-a-user)(username, since, per_page, page): *List gists for a user*" ], "text/plain": [ "- [gists.list](https://docs.github.com/rest/gists/gists#list-gists-for-the-authenticated-user)(since, per_page, page): *List gists for the authenticated user*\n", @@ -394,12 +390,13 @@ " param_types: Dict = field(default_factory=dict)\n", " param_defaults: Dict = field(default_factory=dict)\n", " param_docs: Dict = field(default_factory=dict)\n", + " body_examples: Dict = field(default_factory=dict)\n", " docs_url: str = \"\"\n", " \n", " def mk_doc(self):\n", " rows = []\n", " for f,v in vars(self).items():\n", - " if f not in ('param_types','param_defaults','param_docs'): rows.append(f'| `{f}` | {v} |')\n", + " if f not in ('param_types','param_defaults','param_docs','body_examples'): rows.append(f'| `{f}` | {v} |')\n", " md = f'| Field | Value |\\n|---|---|\\n' + '\\n'.join(rows)\n", " all_params = self.route_params + self.query_params + self.body_params\n", " if all_params:\n", @@ -936,27 +933,9 @@ "name": "stdout", "output_type": "stream", "text": [ - "/assistants/{assistant_id} --> ['assistant_id']\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "/audio/voice_consents/{consent_id} --> ['consent_id']\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "/batches/{batch_id} --> ['batch_id']\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ + "/assistants/{assistant_id} --> ['assistant_id']\n", + "/audio/voice_consents/{consent_id} --> ['consent_id']\n", + "/batches/{batch_id} --> ['batch_id']\n", "/batches/{batch_id}/cancel --> ['batch_id']\n" ] } @@ -976,27 +955,9 @@ "name": "stdout", "output_type": "stream", "text": [ - "/v1/models/{model_id} --> ['model_id']\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "/v1/messages/batches/{message_batch_id} --> ['message_batch_id']\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "/v1/messages/batches/{message_batch_id}/cancel --> ['message_batch_id']\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ + "/v1/models/{model_id} --> ['model_id']\n", + "/v1/messages/batches/{message_batch_id} --> ['message_batch_id']\n", + "/v1/messages/batches/{message_batch_id}/cancel --> ['message_batch_id']\n", "/v1/messages/batches/{message_batch_id}/results --> ['message_batch_id']\n" ] } @@ -1446,28 +1407,10 @@ "name": "stdout", "output_type": "stream", "text": [ - "['issue_field_id'] ['issue_field_id']\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "['name', 'data_type'] ['data_type', 'name']\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "['name', 'data_type', 'single_select_options'] ['single_select_options', 'data_type', 'name']\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "['name', 'data_type', 'iteration_configuration'] ['data_type', 'name', 'iteration_configuration']\n" + "['issue_field_id'] ['issue_field_id']\n", + "['name', 'data_type'] ['name', 'data_type']\n", + "['name', 'data_type', 'single_select_options'] ['name', 'single_select_options', 'data_type']\n", + "['name', 'data_type', 'iteration_configuration'] ['name', 'iteration_configuration', 'data_type']\n" ] }, { @@ -1739,8 +1682,6 @@ { "data": { "text/markdown": [ - "
\n", - "\n", "```python\n", "{ 'param_defaults': {},\n", " 'param_docs': {'batch_id': 'The ID of the batch to cancel.'},\n", @@ -1748,9 +1689,7 @@ " 'query_params': [],\n", " 'required_params': {'batch_id'},\n", " 'route_params': ['batch_id']}\n", - "```\n", - "\n", - "
" + "```" ], "text/plain": [ "{'route_params': ['batch_id'],\n", @@ -1789,8 +1728,6 @@ { "data": { "text/markdown": [ - "
\n", - "\n", "```python\n", "{ 'param_defaults': {},\n", " 'param_docs': { 'anthropic-beta': 'Optional header to specify the beta '\n", @@ -1817,9 +1754,7 @@ " 'query_params': [],\n", " 'required_params': {'file_id'},\n", " 'route_params': ['file_id']}\n", - "```\n", - "\n", - "
" + "```" ], "text/plain": [ "{'route_params': ['file_id'],\n", @@ -1915,10 +1850,13 @@ " rb = _resolve_obj(op.get(\"requestBody\", {}), spec)\n", " content = rb.get(\"content\", {})\n", " ct = first((ct for ct in ctypes if ct in content), None)\n", - " schema = content.get(ct, {}).get(\"schema\") if ct else None\n", + " mt = content.get(ct) or {}\n", + " schema = mt.get(\"schema\")\n", + " exs = mt.get(\"examples\") or ({\"default\": {\"value\": mt[\"example\"]}} if \"example\" in mt else {})\n", + " bexs = {k: {\"summary\": r.get(\"summary\",\"\"), \"value\": r[\"value\"]} for k,v in exs.items() if \"value\" in (r := _resolve_obj(v, spec))}\n", " if not schema:\n", " return AttrDict(body_params=[], file_params=[], required_params=set(), param_types={},\n", - " param_docs={}, param_defaults={}, request_content_type=ct)\n", + " param_docs={}, param_defaults={}, request_content_type=ct, body_examples=bexs)\n", " props, req = _schema_props_required(schema, spec)\n", " fparams = [k for k,v in props.items() if _resolve_obj(v, spec).get(\"format\") == \"binary\"]\n", " bparams = [k for k in props if k not in fparams]\n", @@ -1928,7 +1866,7 @@ " # Params without a default or nullable type are required\n", " # req |= {k for k in props if k not in defaults} # too aggressive doesn't match when spec is incomplete\n", " return AttrDict(body_params=bparams, file_params=fparams, required_params=req, param_types=ptypes,\n", - " param_docs=pdocs, param_defaults=defaults, request_content_type=ct)" + " param_docs=pdocs, param_defaults=defaults, request_content_type=ct, body_examples=bexs)" ] }, { @@ -2101,7 +2039,7 @@ " required_params=sorted(pdict.required_params | bpdict.required_params),\n", " param_types={k:v for k,v in merge(pdict.param_types, bpdict.param_types).items() if v},\n", " param_defaults=_plain(merge(pdict.param_defaults, bpdict.param_defaults)), param_docs=merge(pdict.param_docs, bpdict.param_docs),\n", - " docs_url=_op_docs_url(op) or \"\"))\n", + " docs_url=_op_docs_url(op) or \"\", body_examples=_plain(bpdict.body_examples)))\n", " return res" ] }, @@ -2145,8 +2083,6 @@ { "data": { "text/markdown": [ - "
\n", - "\n", "| Field | Value |\n", "|---|---|\n", "| `group` | apps |\n", @@ -2160,12 +2096,10 @@ "| `file_params` | [] |\n", "| `request_content_type` | |\n", "| `required_params` | [] |\n", - "| `docs_url` | https://docs.github.com/rest/apps/webhooks#get-a-webhook-configuration-for-an-app |\n", - "\n", - "
" + "| `docs_url` | https://docs.github.com/rest/apps/webhooks#get-a-webhook-configuration-for-an-app |" ], "text/plain": [ - "OpSpec(group='apps', name='get_webhook_config_for_app', path='/app/hook/config', verb='GET', summary='Get a webhook configuration for an app', route_params=[], query_params=[], body_params=[], file_params=[], request_content_type='', required_params=[], param_types={}, param_defaults={}, param_docs={}, docs_url='https://docs.github.com/rest/apps/webhooks#get-a-webhook-configuration-for-an-app')" + "OpSpec(group='apps', name='get_webhook_config_for_app', path='/app/hook/config', verb='GET', summary='Get a webhook configuration for an app', route_params=[], query_params=[], body_params=[], file_params=[], request_content_type='', required_params=[], param_types={}, param_defaults={}, param_docs={}, body_examples={}, docs_url='https://docs.github.com/rest/apps/webhooks#get-a-webhook-configuration-for-an-app')" ] }, "execution_count": null, @@ -2186,8 +2120,6 @@ { "data": { "text/markdown": [ - "
\n", - "\n", "| Field | Value |\n", "|---|---|\n", "| `group` | accounts |\n", @@ -2207,13 +2139,10 @@ "|---|---|---|---|---|\n", "| `account` | str | | ✓ | |\n", "| `id` | str | | ✓ | Unique identifier for the external account to be retrieved. |\n", - "| `expand` | list | | | Specifies which fields in the response should be expanded. |\n", - "\n", - "\n", - "
" + "| `expand` | list | | | Specifies which fields in the response should be expanded. |\n" ], "text/plain": [ - "OpSpec(group='accounts', name='get_accounts_account_bank_accounts_id', path='/v1/accounts/{account}/bank_accounts/{id}', verb='GET', summary='Retrieve an external account', route_params=['account', 'id'], query_params=['expand'], body_params=[], file_params=[], request_content_type='application/x-www-form-urlencoded', required_params=['account', 'id'], param_types={'account': , 'expand': , 'id': }, param_defaults={}, param_docs={'expand': 'Specifies which fields in the response should be expanded.', 'id': 'Unique identifier for the external account to be retrieved.'}, docs_url='')" + "OpSpec(group='accounts', name='get_accounts_account_bank_accounts_id', path='/v1/accounts/{account}/bank_accounts/{id}', verb='GET', summary='Retrieve an external account', route_params=['account', 'id'], query_params=['expand'], body_params=[], file_params=[], request_content_type='application/x-www-form-urlencoded', required_params=['account', 'id'], param_types={'account': , 'expand': , 'id': }, param_defaults={}, param_docs={'expand': 'Specifies which fields in the response should be expanded.', 'id': 'Unique identifier for the external account to be retrieved.'}, body_examples={}, docs_url='')" ] }, "execution_count": null, @@ -2234,8 +2163,6 @@ { "data": { "text/markdown": [ - "
\n", - "\n", "| Field | Value |\n", "|---|---|\n", "| `group` | assistants |\n", @@ -2256,13 +2183,10 @@ "| `limit` | int | 20 | | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. |\n", "| `order` | str | desc | | Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. |\n", "| `after` | str | | | A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. |\n", - "| `before` | str | | | A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. |\n", - "\n", - "\n", - "
" + "| `before` | str | | | A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. |\n" ], "text/plain": [ - "OpSpec(group='assistants', name='list_assistants', path='/assistants', verb='GET', summary='Returns a list of assistants.', route_params=[], query_params=['limit', 'order', 'after', 'before'], body_params=[], file_params=[], request_content_type='', required_params=[], param_types={'limit': , 'order': , 'after': , 'before': }, param_defaults={'limit': 20, 'order': 'desc'}, param_docs={'limit': 'A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.', 'order': 'Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.', 'after': 'A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.', 'before': 'A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.'}, docs_url='')" + "OpSpec(group='assistants', name='list_assistants', path='/assistants', verb='GET', summary='Returns a list of assistants.', route_params=[], query_params=['limit', 'order', 'after', 'before'], body_params=[], file_params=[], request_content_type='', required_params=[], param_types={'limit': , 'order': , 'after': , 'before': }, param_defaults={'limit': 20, 'order': 'desc'}, param_docs={'limit': 'A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.', 'order': 'Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.', 'after': 'A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.', 'before': 'A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.'}, body_examples={}, docs_url='')" ] }, "execution_count": null, @@ -2283,8 +2207,6 @@ { "data": { "text/markdown": [ - "
\n", - "\n", "| Field | Value |\n", "|---|---|\n", "| `group` | messages |\n", @@ -2319,13 +2241,10 @@ "| `tool_choice` | dict | | | How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all. |\n", "| `tools` | list | | | Definitions of tools that the model may use. If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview\\#server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-search-tool)). Each tool definition includes: * `name`: Name of the tool. * `description`: Optional, but strongly-recommended description of the tool. * `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. For example, if you defined `tools` as: ```json [ { \"name\": \"get_stock_price\", \"description\": \"Get the current stock price for a given ticker symbol.\", \"input_schema\": { \"type\": \"object\", \"properties\": { \"ticker\": { \"type\": \"string\", \"description\": \"The stock ticker symbol, e.g. AAPL for Apple Inc.\" } }, \"required\": [\"ticker\"] } } ] ``` And then asked the model \"What's the S&P 500 at today?\", the model might produce `tool_use` content blocks in the response like this: ```json [ { \"type\": \"tool_use\", \"id\": \"toolu_01D7FLrfh4GYq7yT1ULFeyMV\", \"name\": \"get_stock_price\", \"input\": { \"ticker\": \"^GSPC\" } } ] ``` You might then run your `get_stock_price` tool with `{\"ticker\": \"^GSPC\"}` as an input, and return the following back to the model in a subsequent `user` message: ```json [ { \"type\": \"tool_result\", \"tool_use_id\": \"toolu_01D7FLrfh4GYq7yT1ULFeyMV\", \"content\": \"259.75 USD\" } ] ``` Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. See our [guide](https://docs.claude.com/en/docs/tool-use) for more details. |\n", "| `top_k` | int | | | Only sample from the top K options for each subsequent token. Used to remove \"long tail\" low probability responses. [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277). Recommended for advanced use cases only. You usually only need to use `temperature`. |\n", - "| `top_p` | float | | | Use nucleus sampling. In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`. You should either alter `temperature` or `top_p`, but not both. Recommended for advanced use cases only. You usually only need to use `temperature`. |\n", - "\n", - "\n", - "
" + "| `top_p` | float | | | Use nucleus sampling. In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`. You should either alter `temperature` or `top_p`, but not both. Recommended for advanced use cases only. You usually only need to use `temperature`. |\n" ], "text/plain": [ - "OpSpec(group='messages', name='messages_post', path='/v1/messages', verb='POST', summary='Create a Message', route_params=[], query_params=[], body_params=['model', 'messages', 'cache_control', 'container', 'inference_geo', 'max_tokens', 'metadata', 'output_config', 'service_tier', 'stop_sequences', 'stream', 'system', 'temperature', 'thinking', 'tool_choice', 'tools', 'top_k', 'top_p'], file_params=[], request_content_type='application/json', required_params=['max_tokens', 'messages', 'model'], param_types={'anthropic-version': , 'model': , 'messages': , 'cache_control': , 'container': , 'inference_geo': , 'max_tokens': , 'metadata': , 'output_config': , 'service_tier': , 'stop_sequences': , 'stream': , 'temperature': , 'thinking': , 'tool_choice': , 'tools': , 'top_k': , 'top_p': }, param_defaults={'cache_control': None, 'container': None, 'inference_geo': None}, param_docs={'anthropic-version': 'The version of the Claude API you want to use. Read more about versioning and our version history [here](https://docs.claude.com/en/api/versioning).', 'model': 'The model that will complete your prompt.\\\\n\\\\nSee [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.', 'messages': 'Input messages. Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model\\'s response. Example with a single `user` message: ```json [{\"role\": \"user\", \"content\": \"Hello, Claude\"}] ``` Example with multiple conversational turns: ```json [ {\"role\": \"user\", \"content\": \"Hello there.\"}, {\"role\": \"assistant\", \"content\": \"Hi, I\\'m Claude. How can I help you?\"}, {\"role\": \"user\", \"content\": \"Can you explain LLMs in plain English?\"}, ] ``` Example with a partially-filled response from Claude: ```json [ {\"role\": \"user\", \"content\": \"What\\'s the Greek name for Sun? (A) Sol (B) Helios (C) Sun\"}, {\"role\": \"assistant\", \"content\": \"The best answer is (\"}, ] ``` Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `\"text\"`. The following input messages are equivalent: ```json {\"role\": \"user\", \"content\": \"Hello, Claude\"} ``` ```json {\"role\": \"user\", \"content\": [{\"type\": \"text\", \"text\": \"Hello, Claude\"}]} ``` See [input examples](https://docs.claude.com/en/api/messages-examples). Note that if you want to include a [system prompt](https://docs.claude.com/en/docs/system-prompts), you can use the top-level `system` parameter — there is no `\"system\"` role for input messages in the Messages API. There is a limit of 100,000 messages in a single request.', 'cache_control': 'Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request.', 'container': 'Container identifier for reuse across requests.', 'inference_geo': \"Specifies the geographic region for inference processing. If not specified, the workspace's `default_inference_geo` is used.\", 'max_tokens': 'The maximum number of tokens to generate before stopping. Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate. Different models have different maximum values for this parameter. See [models](https://docs.claude.com/en/docs/models-overview) for details.', 'metadata': 'An object describing metadata about the request.', 'output_config': \"Configuration options for the model's output, such as the output format.\", 'service_tier': 'Determines whether to use priority capacity (if available) or standard capacity for this request. Anthropic offers different levels of service for your API requests. See [service-tiers](https://docs.claude.com/en/api/service-tiers) for details.', 'stop_sequences': 'Custom text sequences that will cause the model to stop generating. Our models will normally stop when they have naturally completed their turn, which will result in a response `stop_reason` of `\"end_turn\"`. If you want the model to stop generating when it encounters custom strings of text, you can use the `stop_sequences` parameter. If the model encounters one of the custom sequences, the response `stop_reason` value will be `\"stop_sequence\"` and the response `stop_sequence` value will contain the matched stop sequence.', 'stream': 'Whether to incrementally stream the response using server-sent events. See [streaming](https://docs.claude.com/en/api/messages-streaming) for details.', 'system': 'System prompt. A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.claude.com/en/docs/system-prompts).', 'temperature': 'Amount of randomness injected into the response. Defaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks. Note that even with `temperature` of `0.0`, the results will not be fully deterministic.', 'thinking': \"Configuration for enabling Claude's extended thinking. When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details.\", 'tool_choice': 'How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all.', 'tools': 'Definitions of tools that the model may use. If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model\\'s use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview\\\\#server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-search-tool)). Each tool definition includes: * `name`: Name of the tool. * `description`: Optional, but strongly-recommended description of the tool. * `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. For example, if you defined `tools` as: ```json [ { \"name\": \"get_stock_price\", \"description\": \"Get the current stock price for a given ticker symbol.\", \"input_schema\": { \"type\": \"object\", \"properties\": { \"ticker\": { \"type\": \"string\", \"description\": \"The stock ticker symbol, e.g. AAPL for Apple Inc.\" } }, \"required\": [\"ticker\"] } } ] ``` And then asked the model \"What\\'s the S&P 500 at today?\", the model might produce `tool_use` content blocks in the response like this: ```json [ { \"type\": \"tool_use\", \"id\": \"toolu_01D7FLrfh4GYq7yT1ULFeyMV\", \"name\": \"get_stock_price\", \"input\": { \"ticker\": \"^GSPC\" } } ] ``` You might then run your `get_stock_price` tool with `{\"ticker\": \"^GSPC\"}` as an input, and return the following back to the model in a subsequent `user` message: ```json [ { \"type\": \"tool_result\", \"tool_use_id\": \"toolu_01D7FLrfh4GYq7yT1ULFeyMV\", \"content\": \"259.75 USD\" } ] ``` Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. See our [guide](https://docs.claude.com/en/docs/tool-use) for more details.', 'top_k': 'Only sample from the top K options for each subsequent token. Used to remove \"long tail\" low probability responses. [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277). Recommended for advanced use cases only. You usually only need to use `temperature`.', 'top_p': 'Use nucleus sampling. In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`. You should either alter `temperature` or `top_p`, but not both. Recommended for advanced use cases only. You usually only need to use `temperature`.'}, docs_url='https://docs.claude.com/en/docs/initial-setup')" + "OpSpec(group='messages', name='messages_post', path='/v1/messages', verb='POST', summary='Create a Message', route_params=[], query_params=[], body_params=['model', 'messages', 'cache_control', 'container', 'inference_geo', 'max_tokens', 'metadata', 'output_config', 'service_tier', 'stop_sequences', 'stream', 'system', 'temperature', 'thinking', 'tool_choice', 'tools', 'top_k', 'top_p'], file_params=[], request_content_type='application/json', required_params=['max_tokens', 'messages', 'model'], param_types={'anthropic-version': , 'model': , 'messages': , 'cache_control': , 'container': , 'inference_geo': , 'max_tokens': , 'metadata': , 'output_config': , 'service_tier': , 'stop_sequences': , 'stream': , 'temperature': , 'thinking': , 'tool_choice': , 'tools': , 'top_k': , 'top_p': }, param_defaults={'cache_control': None, 'container': None, 'inference_geo': None}, param_docs={'anthropic-version': 'The version of the Claude API you want to use. Read more about versioning and our version history [here](https://docs.claude.com/en/api/versioning).', 'model': 'The model that will complete your prompt.\\\\n\\\\nSee [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.', 'messages': 'Input messages. Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model\\'s response. Example with a single `user` message: ```json [{\"role\": \"user\", \"content\": \"Hello, Claude\"}] ``` Example with multiple conversational turns: ```json [ {\"role\": \"user\", \"content\": \"Hello there.\"}, {\"role\": \"assistant\", \"content\": \"Hi, I\\'m Claude. How can I help you?\"}, {\"role\": \"user\", \"content\": \"Can you explain LLMs in plain English?\"}, ] ``` Example with a partially-filled response from Claude: ```json [ {\"role\": \"user\", \"content\": \"What\\'s the Greek name for Sun? (A) Sol (B) Helios (C) Sun\"}, {\"role\": \"assistant\", \"content\": \"The best answer is (\"}, ] ``` Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `\"text\"`. The following input messages are equivalent: ```json {\"role\": \"user\", \"content\": \"Hello, Claude\"} ``` ```json {\"role\": \"user\", \"content\": [{\"type\": \"text\", \"text\": \"Hello, Claude\"}]} ``` See [input examples](https://docs.claude.com/en/api/messages-examples). Note that if you want to include a [system prompt](https://docs.claude.com/en/docs/system-prompts), you can use the top-level `system` parameter — there is no `\"system\"` role for input messages in the Messages API. There is a limit of 100,000 messages in a single request.', 'cache_control': 'Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request.', 'container': 'Container identifier for reuse across requests.', 'inference_geo': \"Specifies the geographic region for inference processing. If not specified, the workspace's `default_inference_geo` is used.\", 'max_tokens': 'The maximum number of tokens to generate before stopping. Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate. Different models have different maximum values for this parameter. See [models](https://docs.claude.com/en/docs/models-overview) for details.', 'metadata': 'An object describing metadata about the request.', 'output_config': \"Configuration options for the model's output, such as the output format.\", 'service_tier': 'Determines whether to use priority capacity (if available) or standard capacity for this request. Anthropic offers different levels of service for your API requests. See [service-tiers](https://docs.claude.com/en/api/service-tiers) for details.', 'stop_sequences': 'Custom text sequences that will cause the model to stop generating. Our models will normally stop when they have naturally completed their turn, which will result in a response `stop_reason` of `\"end_turn\"`. If you want the model to stop generating when it encounters custom strings of text, you can use the `stop_sequences` parameter. If the model encounters one of the custom sequences, the response `stop_reason` value will be `\"stop_sequence\"` and the response `stop_sequence` value will contain the matched stop sequence.', 'stream': 'Whether to incrementally stream the response using server-sent events. See [streaming](https://docs.claude.com/en/api/messages-streaming) for details.', 'system': 'System prompt. A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.claude.com/en/docs/system-prompts).', 'temperature': 'Amount of randomness injected into the response. Defaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks. Note that even with `temperature` of `0.0`, the results will not be fully deterministic.', 'thinking': \"Configuration for enabling Claude's extended thinking. When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit. See [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details.\", 'tool_choice': 'How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all.', 'tools': 'Definitions of tools that the model may use. If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model\\'s use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview\\\\#server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-search-tool)). Each tool definition includes: * `name`: Name of the tool. * `description`: Optional, but strongly-recommended description of the tool. * `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. For example, if you defined `tools` as: ```json [ { \"name\": \"get_stock_price\", \"description\": \"Get the current stock price for a given ticker symbol.\", \"input_schema\": { \"type\": \"object\", \"properties\": { \"ticker\": { \"type\": \"string\", \"description\": \"The stock ticker symbol, e.g. AAPL for Apple Inc.\" } }, \"required\": [\"ticker\"] } } ] ``` And then asked the model \"What\\'s the S&P 500 at today?\", the model might produce `tool_use` content blocks in the response like this: ```json [ { \"type\": \"tool_use\", \"id\": \"toolu_01D7FLrfh4GYq7yT1ULFeyMV\", \"name\": \"get_stock_price\", \"input\": { \"ticker\": \"^GSPC\" } } ] ``` You might then run your `get_stock_price` tool with `{\"ticker\": \"^GSPC\"}` as an input, and return the following back to the model in a subsequent `user` message: ```json [ { \"type\": \"tool_result\", \"tool_use_id\": \"toolu_01D7FLrfh4GYq7yT1ULFeyMV\", \"content\": \"259.75 USD\" } ] ``` Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. See our [guide](https://docs.claude.com/en/docs/tool-use) for more details.', 'top_k': 'Only sample from the top K options for each subsequent token. Used to remove \"long tail\" low probability responses. [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277). Recommended for advanced use cases only. You usually only need to use `temperature`.', 'top_p': 'Use nucleus sampling. In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`. You should either alter `temperature` or `top_p`, but not both. Recommended for advanced use cases only. You usually only need to use `temperature`.'}, body_examples={}, docs_url='https://docs.claude.com/en/docs/initial-setup')" ] }, "execution_count": null, @@ -2562,8 +2481,6 @@ { "data": { "text/markdown": [ - "
\n", - "\n", "```python\n", "{ 'description': 'Generates a model response given an input '\n", " '`GenerateContentRequest`. Refer to the [text generation '\n", @@ -2589,9 +2506,7 @@ " 'path': 'v1beta/{+model}:generateContent',\n", " 'request': {'$ref': 'GenerateContentRequest'},\n", " 'response': {'$ref': 'GenerateContentResponse'}}\n", - "```\n", - "\n", - "
" + "```" ], "text/plain": [ "{'id': 'generativelanguage.models.generateContent',\n", @@ -2657,8 +2572,6 @@ { "data": { "text/markdown": [ - "
\n", - "\n", "```python\n", "{ 'cachedContent': { 'description': 'Optional. The name of the content '\n", " '[cached](https://ai.google.dev/gemini-api/docs/caching) '\n", @@ -2746,9 +2659,7 @@ " 'guides to learn more.',\n", " 'items': {'$ref': 'Tool'},\n", " 'type': 'array'}}\n", - "```\n", - "\n", - "
" + "```" ], "text/plain": [ "{'model': {'description': 'Required. The name of the `Model` to use for generating the completion. Format: `models/{model}`.',\n", @@ -2933,7 +2844,28 @@ "execution_count": null, "id": "cdf29251", "metadata": {}, - "outputs": [], + "outputs": [ + { + "data": { + "text/plain": [ + "['access_token',\n", + " 'alt',\n", + " 'callback',\n", + " 'fields',\n", + " 'key',\n", + " 'oauth_token',\n", + " 'prettyPrint',\n", + " 'quotaUser',\n", + " 'upload_protocol',\n", + " 'uploadType',\n", + " '$.xgafv']" + ] + }, + "execution_count": null, + "metadata": {}, + "output_type": "execute_result" + } + ], "source": [ "op = first(gem_ops, lambda o: o.name=='generate_content')\n", "assert {'alt','fields','quotaUser'} <= set(op.query_params)\n", @@ -2949,8 +2881,6 @@ { "data": { "text/markdown": [ - "
\n", - "\n", "| Field | Value |\n", "|---|---|\n", "| `group` | ['models'] |\n", @@ -2959,7 +2889,7 @@ "| `verb` | POST |\n", "| `summary` | Generates multiple embedding vectors from the input `Content` which consists of a batch of strings represented as `EmbedContentRequest` objects. |\n", "| `route_params` | ['model'] |\n", - "| `query_params` | [] |\n", + "| `query_params` | ['access_token', 'alt', 'callback', 'fields', 'key', 'oauth_token', 'prettyPrint', 'quotaUser', 'upload_protocol', 'uploadType', '$.xgafv'] |\n", "| `body_params` | ['requests'] |\n", "| `file_params` | [] |\n", "| `request_content_type` | |\n", @@ -2969,13 +2899,21 @@ "| Param | Type | Default | Required | Description |\n", "|---|---|---|---|---|\n", "| `model` | str | | ✓ | Required. The model's resource name. This serves as an ID for the Model to use. This name should match a model name returned by the `ListModels` method. Format: `models/{model}` |\n", - "| `requests` | list | | ✓ | Required. Embed requests for the batch. The model in each of these requests must match the model specified `BatchEmbedContentsRequest.model`. |\n", - "\n", - "\n", - "
" + "| `access_token` | str | | | OAuth access token. |\n", + "| `alt` | str | | | Data format for response. |\n", + "| `callback` | str | | | JSONP |\n", + "| `fields` | str | | | Selector specifying which fields to include in a partial response. |\n", + "| `key` | str | | | API key. Your API key identifies your project and provides you with API access, quota, and reports. Required unless you provide an OAuth 2.0 token. |\n", + "| `oauth_token` | str | | | OAuth 2.0 token for the current user. |\n", + "| `prettyPrint` | bool | | | Returns response with indentations and line breaks. |\n", + "| `quotaUser` | str | | | Available to use for quota purposes for server-side applications. Can be any arbitrary string assigned to a user, but should not exceed 40 characters. |\n", + "| `upload_protocol` | str | | | Upload protocol for media (e.g. \"raw\", \"multipart\"). |\n", + "| `uploadType` | str | | | Legacy upload protocol for media (e.g. \"media\", \"multipart\"). |\n", + "| `$.xgafv` | str | | | V1 error format. |\n", + "| `requests` | list | | ✓ | Required. Embed requests for the batch. The model in each of these requests must match the model specified `BatchEmbedContentsRequest.model`. |\n" ], "text/plain": [ - "OpSpec(group=['models'], name='batch_embed_contents', path='v1beta/{+model}:batchEmbedContents', verb='POST', summary='Generates multiple embedding vectors from the input `Content` which consists of a batch of strings represented as `EmbedContentRequest` objects.', route_params=['model'], query_params=[], body_params=['requests'], file_params=[], request_content_type='', required_params=['model', 'requests'], param_types={'model': , 'requests': }, param_defaults={}, param_docs={'model': \"Required. The model's resource name. This serves as an ID for the Model to use. This name should match a model name returned by the `ListModels` method. Format: `models/{model}`\", 'requests': 'Required. Embed requests for the batch. The model in each of these requests must match the model specified `BatchEmbedContentsRequest.model`.'}, docs_url='')" + "OpSpec(group=['models'], name='batch_embed_contents', path='v1beta/{+model}:batchEmbedContents', verb='POST', summary='Generates multiple embedding vectors from the input `Content` which consists of a batch of strings represented as `EmbedContentRequest` objects.', route_params=['model'], query_params=['access_token', 'alt', 'callback', 'fields', 'key', 'oauth_token', 'prettyPrint', 'quotaUser', 'upload_protocol', 'uploadType', '$.xgafv'], body_params=['requests'], file_params=[], request_content_type='', required_params=['model', 'requests'], param_types={'model': , 'access_token': , 'alt': , 'callback': , 'fields': , 'key': , 'oauth_token': , 'prettyPrint': , 'quotaUser': , 'upload_protocol': , 'uploadType': , '$.xgafv': , 'requests': }, param_defaults={}, param_docs={'model': \"Required. The model's resource name. This serves as an ID for the Model to use. This name should match a model name returned by the `ListModels` method. Format: `models/{model}`\", 'access_token': 'OAuth access token.', 'alt': 'Data format for response.', 'callback': 'JSONP', 'fields': 'Selector specifying which fields to include in a partial response.', 'key': 'API key. Your API key identifies your project and provides you with API access, quota, and reports. Required unless you provide an OAuth 2.0 token.', 'oauth_token': 'OAuth 2.0 token for the current user.', 'prettyPrint': 'Returns response with indentations and line breaks.', 'quotaUser': 'Available to use for quota purposes for server-side applications. Can be any arbitrary string assigned to a user, but should not exceed 40 characters.', 'upload_protocol': 'Upload protocol for media (e.g. \"raw\", \"multipart\").', 'uploadType': 'Legacy upload protocol for media (e.g. \"media\", \"multipart\").', '$.xgafv': 'V1 error format.', 'requests': 'Required. Embed requests for the batch. The model in each of these requests must match the model specified `BatchEmbedContentsRequest.model`.'}, body_examples={}, docs_url='')" ] }, "execution_count": null, @@ -3121,7 +3059,7 @@ "name": "stdout", "output_type": "stream", "text": [ - "1.32MB, vs 12.2MB raw\n" + "1.42MB, vs 12.2MB raw\n" ] } ], diff --git a/nbs/04_oapi.ipynb b/nbs/04_oapi.ipynb index 1a776b0..cae2cb4 100644 --- a/nbs/04_oapi.ipynb +++ b/nbs/04_oapi.ipynb @@ -320,7 +320,7 @@ "| `before` | str | | | A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. |\n" ], "text/plain": [ - "OpSpec(group='assistants', name='list_assistants', path='/assistants', verb='GET', summary='Returns a list of assistants.', route_params=[], query_params=['limit', 'order', 'after', 'before'], body_params=[], file_params=[], request_content_type='', required_params=[], param_types={'limit': , 'order': , 'after': , 'before': }, param_defaults={'limit': 20, 'order': 'desc'}, param_docs={'limit': 'A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.', 'order': 'Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.', 'after': 'A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.', 'before': 'A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.'}, docs_url='')" + "OpSpec(group='assistants', name='list_assistants', path='/assistants', verb='GET', summary='Returns a list of assistants.', route_params=[], query_params=['limit', 'order', 'after', 'before'], body_params=[], file_params=[], request_content_type='', required_params=[], param_types={'limit': , 'order': , 'after': , 'before': }, param_defaults={'limit': 20, 'order': 'desc'}, param_docs={'limit': 'A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.', 'order': 'Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.', 'after': 'A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.', 'before': 'A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.'}, body_examples={}, docs_url='')" ] }, "execution_count": null, @@ -479,6 +479,11 @@ }, "outputs": [], "source": [ + "def _examples_doc(exs):\n", + " \"Render body examples as an `Examples:` doc section, one fenced JSON block per example\"\n", + " if not exs: return ''\n", + " return '\\n\\nExamples:' + ''.join(f\"\\n- {v.get('summary') or k}:\\n```json\\n{json.dumps(v['value'], indent=2)}\\n```\" for k,v in exs.items())\n", + "\n", "class OpFunc:\n", " def __init__(self, op_spec, client, base_url, form_encoder=None, defaults=None):\n", " store_attr()\n", @@ -499,7 +504,7 @@ " self.required_params = op_spec.required_params\n", " self.param_docs = op_spec.param_docs\n", " self.__signature__ = mk_sig(op_spec, self.sparams, self.defaults)\n", - " self.__doc__ = mk_doc(self, self.__signature__, self.sparams)\n", + " self.__doc__ = mk_doc(self, self.__signature__, self.sparams) + _examples_doc(op_spec.body_examples)\n", "\n", " def _repr_markdown_(self): return self.__doc__\n", " def __repr__(self): return f\"{'.'.join(snake(g) for g in listify(self.group))}.{self.name}{self.__signature__}\\n{self.docs_url}\"\n" @@ -539,6 +544,36 @@ "opf.group, opf.name, opf.__signature__, opf.__doc__" ] }, + { + "cell_type": "markdown", + "id": "bf1d6495", + "metadata": {}, + "source": [ + "Where a spec supplies request examples, you can see the examples in the doc too:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "0b9fc3a3", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "'Creates an edited or extended image given one or more source images and a prompt. This endpoint supports GPT Image models (`gpt-image-1.5`, `gpt-image-1`, `gpt-image-1-mini`, and `chatgpt-image-latest`) and `dall-e-2`.\\n\\nParameters:\\n- images (list, required): Input image references to edit. For GPT image models, you can provide up to 16 images.\\n- prompt (str, required): A text description of the desired image edit.\\n- mask (dict, optional): Reference an input image by either URL or uploaded file ID. Provide exactly one of `image_url` or `file_id`.\\n- input_fidelity (str, optional): Controls fidelity to the original input image(s).\\n- user (str, optional): A unique identifier representing your end-user, which can help OpenAI monitor and detect abuse.\\n- output_compression (int, optional): Compression level for `jpeg` or `webp` output.\\n- model (str, default: \\'gpt-image-1.5\\'): The model to use for image editing.\\n- n (int, default: 1): The number of edited images to generate.\\n- quality (str, default: \\'auto\\'): Output quality for GPT image models.\\n- size (str, default: \\'auto\\'): Requested output image size.\\n- output_format (str, default: \\'png\\'): Output image format. Supported for GPT image models.\\n- moderation (str, default: \\'auto\\'): Moderation level for GPT image models.\\n- background (str, default: \\'auto\\'): Background behavior for generated image output.\\n- stream (bool, default: False): Stream partial image results as events.\\n- partial_images (int, default: 0): The number of partial images to generate. This parameter is used for streaming responses that return partial images. Value must be between 0 and 3. When set to 0, the response will be a single image sent in one streaming event. Note that the final image may be sent before the full number of partial images are generated if the full image is generated more quickly.\\n\\nExamples:\\n- JSON request with image URL:\\n```json\\n{\\n \"model\": \"gpt-image-1.5\",\\n \"prompt\": \"Add a watercolor effect to this image\",\\n \"images\": [\\n {\\n \"image_url\": \"https://example.com/source-image.png\"\\n }\\n ],\\n \"size\": \"1024x1024\",\\n \"quality\": \"high\"\\n}\\n```\\n- JSON request with uploaded file id:\\n```json\\n{\\n \"model\": \"gpt-image-1.5\",\\n \"prompt\": \"Replace the background with a snowy mountain scene\",\\n \"images\": [\\n {\\n \"file_id\": \"file-abc123\"\\n }\\n ],\\n \"mask\": {\\n \"file_id\": \"file-mask123\"\\n },\\n \"output_format\": \"png\",\\n \"output_compression\": 100\\n}\\n```'" + ] + }, + "execution_count": null, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "op_ex = first(o for o in oai_spec.ops if o.path=='/images/edits' and o.verb=='POST')\n", + "OpFunc(op_ex, None, '').__doc__" + ] + }, { "cell_type": "markdown", "id": "6a00f1c1", @@ -604,7 +639,18 @@ "execution_count": null, "id": "f4a8b4ae", "metadata": {}, - "outputs": [], + "outputs": [ + { + "data": { + "text/plain": [ + "" + ] + }, + "execution_count": null, + "metadata": {}, + "output_type": "execute_result" + } + ], "source": [ "opf2 = OpFunc(op, None, '')\n", "opf2.defaults = {'after': 'x'}\n", @@ -1020,7 +1066,8 @@ "{'type': 'content_block_delta', 'index': 0, 'delta': {'type': 'text_delta', 'text': 'Hello! How are'}}\n", "{'type': 'content_block_delta', 'index': 0, 'delta': {'type': 'text_delta', 'text': ' you doing today? Is there anything I can help you with?'}}\n", "{'type': 'content_block_stop', 'index': 0}\n", - "{'type': 'message_delta', 'delta': {'stop_reason': 'end_turn', 'stop_sequence': None, 'stop_details': None}, 'usage': {'input_tokens': 9, 'cache_creation_input_tokens': 0, 'cache_read_input_tokens': 0, 'output_tokens': 20}}\n" + "{'type': 'message_delta', 'delta': {'stop_reason': 'end_turn', 'stop_sequence': None, 'stop_details': None}, 'usage': {'input_tokens': 9, 'cache_creation_input_tokens': 0, 'cache_read_input_tokens': 0, 'output_tokens': 20}}\n", + "{'type': 'message_stop'}\n" ] } ], @@ -1067,7 +1114,7 @@ "| `repo` | str | | ✓ | The name of the repository without the `.git` extension. The name is not case sensitive. |\n" ], "text/plain": [ - "OpSpec(group='repos', name='get', path='/repos/{owner}/{repo}', verb='GET', summary='Get a repository', route_params=['owner', 'repo'], query_params=[], body_params=[], file_params=[], request_content_type='', required_params=['owner', 'repo'], param_types={'owner': , 'repo': }, param_defaults={}, param_docs={'owner': 'The account owner of the repository. The name is not case sensitive.', 'repo': 'The name of the repository without the `.git` extension. The name is not case sensitive.'}, docs_url='https://docs.github.com/rest/repos/repos#get-a-repository')" + "OpSpec(group='repos', name='get', path='/repos/{owner}/{repo}', verb='GET', summary='Get a repository', route_params=['owner', 'repo'], query_params=[], body_params=[], file_params=[], request_content_type='', required_params=['owner', 'repo'], param_types={'owner': , 'repo': }, param_defaults={}, param_docs={'owner': 'The account owner of the repository. The name is not case sensitive.', 'repo': 'The name of the repository without the `.git` extension. The name is not case sensitive.'}, body_examples={}, docs_url='https://docs.github.com/rest/repos/repos#get-a-repository')" ] }, "execution_count": null, @@ -1177,8 +1224,8 @@ { "data": { "text/plain": [ - "[batches.list(name: str, filter: str = UNSET, page_size: int = UNSET, page_token: str = UNSET, return_partial_success: bool = UNSET),\n", - " batches.get(name: str)]" + "[batches.list(name: str, filter: str = UNSET, page_size: int = UNSET, page_token: str = UNSET, return_partial_success: bool = UNSET, access_token: str = UNSET, alt: str = UNSET, callback: str = UNSET, fields: str = UNSET, key: str = UNSET, oauth_token: str = UNSET, pretty_print: bool = UNSET, quota_user: str = UNSET, upload_protocol: str = UNSET, upload_type: str = UNSET, xgafv: str = UNSET),\n", + " batches.get(name: str, access_token: str = UNSET, alt: str = UNSET, callback: str = UNSET, fields: str = UNSET, key: str = UNSET, oauth_token: str = UNSET, pretty_print: bool = UNSET, quota_user: str = UNSET, upload_protocol: str = UNSET, upload_type: str = UNSET, xgafv: str = UNSET)]" ] }, "execution_count": null, @@ -1256,12 +1303,23 @@ "Parameters:\n", "- parent (str, required): Required. The parent resource of the `Permission`. Formats: `tunedModels/{tuned_model}` `corpora/{corpus}`\n", "- role (str, required): Required. The role granted by this permission.\n", + "- access_token (str, optional): OAuth access token.\n", + "- alt (str, optional): Data format for response.\n", + "- callback (str, optional): JSONP\n", + "- fields (str, optional): Selector specifying which fields to include in a partial response.\n", + "- key (str, optional): API key. Your API key identifies your project and provides you with API access, quota, and reports. Required unless you provide an OAuth 2.0 token.\n", + "- oauth_token (str, optional): OAuth 2.0 token for the current user.\n", + "- pretty_print (bool, optional): Returns response with indentations and line breaks.\n", + "- quota_user (str, optional): Available to use for quota purposes for server-side applications. Can be any arbitrary string assigned to a user, but should not exceed 40 characters.\n", + "- upload_protocol (str, optional): Upload protocol for media (e.g. \"raw\", \"multipart\").\n", + "- upload_type (str, optional): Legacy upload protocol for media (e.g. \"media\", \"multipart\").\n", + "- xgafv (str, optional): V1 error format.\n", "- name (str, optional): Output only. Identifier. The permission name. A unique name will be generated on create. Examples: tunedModels/{tuned_model}/permissions/{permission} corpora/{corpus}/permissions/{permission} Output only.\n", "- grantee_type (str, optional): Optional. Immutable. The type of the grantee.\n", "- email_address (str, optional): Optional. Immutable. The email address of the user of group which this permission refers. Field is not set when permission's grantee type is EVERYONE." ], "text/plain": [ - "tuned_models.permissions.create(parent: str, role: str, name: str = UNSET, grantee_type: str = UNSET, email_address: str = UNSET)" + "tuned_models.permissions.create(parent: str, role: str, access_token: str = UNSET, alt: str = UNSET, callback: str = UNSET, fields: str = UNSET, key: str = UNSET, oauth_token: str = UNSET, pretty_print: bool = UNSET, quota_user: str = UNSET, upload_protocol: str = UNSET, upload_type: str = UNSET, xgafv: str = UNSET, name: str = UNSET, grantee_type: str = UNSET, email_address: str = UNSET)" ] }, "execution_count": null, @@ -1384,24 +1442,25 @@ "name": "stdout", "output_type": "stream", "text": [ - "- models.generate_content(model, contents, system_instruction, tools, tool_config, safety_settings, generation_config, cached_content, service_tier, store): *Generates a model response given an input `GenerateContentRequest`. Refer to the [text generation guide](https://ai.google.dev/gemini-api/docs/text-generation) for detailed usage information. Input capabilities differ between models, including tuned models. Refer to the [model guide](https://ai.google.dev/gemini-api/docs/models/gemini) and [tuning guide](https://ai.google.dev/gemini-api/docs/model-tuning) for details.*\n", - "- models.generate_answer(model, contents, answer_style, inline_passages, semantic_retriever, safety_settings, temperature): *Generates a grounded answer from the model given an input `GenerateAnswerRequest`.*\n", - "- models.stream_generate_content(model, contents, system_instruction, tools, tool_config, safety_settings, generation_config, cached_content, service_tier, store): *Generates a [streamed response](https://ai.google.dev/gemini-api/docs/text-generation?lang=python#generate-a-text-stream) from the model given an input `GenerateContentRequest`.*\n", - "- models.embed_content(model, content, task_type, title, output_dimensionality): *Generates a text embedding vector from the input `Content` using the specified [Gemini Embedding model](https://ai.google.dev/gemini-api/docs/models/gemini#text-embedding).*\n", - "- models.batch_embed_contents(model, requests): *Generates multiple embedding vectors from the input `Content` which consists of a batch of strings represented as `EmbedContentRequest` objects.*\n", - "- models.count_tokens(model, contents, generate_content_request): *Runs a model's tokenizer on input `Content` and returns the token count. Refer to the [tokens guide](https://ai.google.dev/gemini-api/docs/tokens) to learn more about tokens.*\n", - "- models.batch_generate_content(model, batch): *Enqueues a batch of `GenerateContent` requests for batch processing.*\n", - "- models.async_batch_embed_content(model, batch): *Enqueues a batch of `EmbedContent` requests for batch processing. We have a `BatchEmbedContents` handler in `GenerativeService`, but it was synchronized. So we name this one to be `Async` to avoid confusion.*\n", - "- models.generate_message(model, prompt, temperature, candidate_count, top_p, top_k): *Generates a response from the model given an input `MessagePrompt`.*\n", - "- models.count_message_tokens(model, prompt): *Runs a model's tokenizer on a string and returns the token count.*\n", - "- models.get(name): *Gets information about a specific `Model` such as its version number, token limits, [parameters](https://ai.google.dev/gemini-api/docs/models/generative-models#model-parameters) and other metadata. Refer to the [Gemini models guide](https://ai.google.dev/gemini-api/docs/models/gemini) for detailed model information.*\n", - "- models.list(page_size, page_token): *Lists the [`Model`s](https://ai.google.dev/gemini-api/docs/models/gemini) available through the Gemini API.*\n", - "- models.predict(model, instances, parameters): *Performs a prediction request.*\n", - "- models.predict_long_running(model, instances, parameters): *Same as Predict but returns an LRO.*\n", - "- models.generate_text(model, prompt, temperature, candidate_count, max_output_tokens, top_p, top_k, safety_settings, stop_sequences): *Generates a response from the model given an input message.*\n", - "- models.embed_text(model, text): *Generates an embedding from the model given an input message.*\n", - "- models.batch_embed_text(model, texts, requests): *Generates multiple embeddings from the model given input text in a synchronous call.*\n", - "- models.count_text_tokens(model, prompt): *Runs a model's tokenizer on a text and returns the token count.*\n" + "- models.generate_content(model, contents, access_token, alt, callback, fields, key, oauth_token, pretty_print, quota_user, upload_protocol, upload_type, xgafv, system_instruction, tools, tool_config, safety_settings, generation_config, cached_content, service_tier, store): *Generates a model response given an input `GenerateContentRequest`. Refer to the [text generation guide](https://ai.google.dev/gemini-api/docs/text-generation) for detailed usage information. Input capabilities differ between models, including tuned models. Refer to the [model guide](https://ai.google.dev/gemini-api/docs/models/gemini) and [tuning guide](https://ai.google.dev/gemini-api/docs/model-tuning) for details.*\n", + "- models.generate_answer(model, contents, answer_style, access_token, alt, callback, fields, key, oauth_token, pretty_print, quota_user, upload_protocol, upload_type, xgafv, inline_passages, semantic_retriever, safety_settings, temperature): *Generates a grounded answer from the model given an input `GenerateAnswerRequest`.*\n", + "- models.stream_generate_content(model, contents, access_token, alt, callback, fields, key, oauth_token, pretty_print, quota_user, upload_protocol, upload_type, xgafv, system_instruction, tools, tool_config, safety_settings, generation_config, cached_content, service_tier, store): *Generates a [streamed response](https://ai.google.dev/gemini-api/docs/text-generation?lang=python#generate-a-text-stream) from the model given an input `GenerateContentRequest`.*\n", + "- models.embed_content(model, content, access_token, alt, callback, fields, key, oauth_token, pretty_print, quota_user, upload_protocol, upload_type, xgafv, task_type, title, output_dimensionality): *Generates a text embedding vector from the input `Content` using the specified [Gemini Embedding model](https://ai.google.dev/gemini-api/docs/models/gemini#text-embedding).*\n", + "- models.batch_embed_contents(model, requests, access_token, alt, callback, fields, key, oauth_token, pretty_print, quota_user, upload_protocol, upload_type, xgafv): *Generates multiple embedding vectors from the input `Content` which consists of a batch of strings represented as `EmbedContentRequest` objects.*\n", + "- models.count_tokens(model, access_token, alt, callback, fields, key, oauth_token, pretty_print, quota_user, upload_protocol, upload_type, xgafv, contents, generate_content_request): *Runs a model's tokenizer on input `Content` and returns the token count. Refer to the [tokens guide](https://ai.google.dev/gemini-api/docs/tokens) to learn more about tokens.*\n", + "- models.batch_generate_content(model, batch, access_token, alt, callback, fields, key, oauth_token, pretty_print, quota_user, upload_protocol, upload_type, xgafv): *Enqueues a batch of `GenerateContent` requests for batch processing.*\n", + "- models.async_batch_embed_content(model, batch, access_token, alt, callback, fields, key, oauth_token, pretty_print, quota_user, upload_protocol, upload_type, xgafv): *Enqueues a batch of `EmbedContent` requests for batch processing. We have a `BatchEmbedContents` handler in `GenerativeService`, but it was synchronized. So we name this one to be `Async` to avoid confusion.*\n", + "- models.generate_message(model, prompt, access_token, alt, callback, fields, key, oauth_token, pretty_print, quota_user, upload_protocol, upload_type, xgafv, temperature, candidate_count, top_p, top_k): *Generates a response from the model given an input `MessagePrompt`.*\n", + "- models.count_message_tokens(model, prompt, access_token, alt, callback, fields, key, oauth_token, pretty_print, quota_user, upload_protocol, upload_type, xgafv): *Runs a model's tokenizer on a string and returns the token count.*\n", + "- models.get(name, access_token, alt, callback, fields, key, oauth_token, pretty_print, quota_user, upload_protocol, upload_type, xgafv): *Gets information about a specific `Model` such as its version number, token limits, [parameters](https://ai.google.dev/gemini-api/docs/models/generative-models#model-parameters) and other metadata. Refer to the [Gemini models guide](https://ai.google.dev/gemini-api/docs/models/gemini) for detailed model information.*\n", + "- models.list(page_size, page_token, access_token, alt, callback, fields, key, oauth_token, pretty_print, quota_user, upload_protocol, upload_type, xgafv): *Lists the [`Model`s](https://ai.google.dev/gemini-api/docs/models/gemini) available through the Gemini API.*\n", + "- models.predict(model, instances, access_token, alt, callback, fields, key, oauth_token, pretty_print, quota_user, upload_protocol, upload_type, xgafv, parameters): *Performs a prediction request.*\n", + "- models.predict_long_running(model, instances, access_token, alt, callback, fields, key, oauth_token, pretty_print, quota_user, upload_protocol, upload_type, xgafv, parameters): *Same as Predict but returns an LRO.*\n", + "- models.generate_text(model, prompt, access_token, alt, callback, fields, key, oauth_token, pretty_print, quota_user, upload_protocol, upload_type, xgafv, temperature, candidate_count, max_output_tokens, top_p, top_k, safety_settings, stop_sequences): *Generates a response from the model given an input message.*\n", + "- models.embed_text(model, access_token, alt, callback, fields, key, oauth_token, pretty_print, quota_user, upload_protocol, upload_type, xgafv, text): *Generates an embedding from the model given an input message.*\n", + "- models.batch_embed_text(model, access_token, alt, callback, fields, key, oauth_token, pretty_print, quota_user, upload_protocol, upload_type, xgafv, texts, requests): *Generates multiple embeddings from the model given input text in a synchronous call.*\n", + "- models.count_text_tokens(model, prompt, access_token, alt, callback, fields, key, oauth_token, pretty_print, quota_user, upload_protocol, upload_type, xgafv): *Runs a model's tokenizer on a text and returns the token count.*\n", + "- operations/\n" ] } ], @@ -1432,6 +1491,17 @@ "Parameters:\n", "- model (str, required): Required. The name of the `Model` to use for generating the completion. Format: `models/{model}`.\n", "- contents (list, required): Required. The content of the current conversation with the model. For single-turn queries, this is a single instance. For multi-turn queries like [chat](https://ai.google.dev/gemini-api/docs/text-generation#chat), this is a repeated field that contains the conversation history and the latest request.\n", + "- access_token (str, optional): OAuth access token.\n", + "- alt (str, optional): Data format for response.\n", + "- callback (str, optional): JSONP\n", + "- fields (str, optional): Selector specifying which fields to include in a partial response.\n", + "- key (str, optional): API key. Your API key identifies your project and provides you with API access, quota, and reports. Required unless you provide an OAuth 2.0 token.\n", + "- oauth_token (str, optional): OAuth 2.0 token for the current user.\n", + "- pretty_print (bool, optional): Returns response with indentations and line breaks.\n", + "- quota_user (str, optional): Available to use for quota purposes for server-side applications. Can be any arbitrary string assigned to a user, but should not exceed 40 characters.\n", + "- upload_protocol (str, optional): Upload protocol for media (e.g. \"raw\", \"multipart\").\n", + "- upload_type (str, optional): Legacy upload protocol for media (e.g. \"media\", \"multipart\").\n", + "- xgafv (str, optional): V1 error format.\n", "- system_instruction (dict, optional): Optional. Developer set [system instruction(s)](https://ai.google.dev/gemini-api/docs/system-instructions). Currently, text only.\n", "- tools (list, optional): Optional. A list of `Tools` the `Model` may use to generate the next response. A `Tool` is a piece of code that enables the system to interact with external systems to perform an action, or set of actions, outside of knowledge and scope of the `Model`. Supported `Tool`s are `Function` and `code_execution`. Refer to the [Function calling](https://ai.google.dev/gemini-api/docs/function-calling) and the [Code execution](https://ai.google.dev/gemini-api/docs/code-execution) guides to learn more.\n", "- tool_config (dict, optional): Optional. Tool configuration for any `Tool` specified in the request. Refer to the [Function calling guide](https://ai.google.dev/gemini-api/docs/function-calling#function_calling_mode) for a usage example.\n", @@ -1639,7 +1709,7 @@ "name": "stdout", "output_type": "stream", "text": [ - "APIError(message='x-api-key header is required', endpoint='POST /v1/messages', status_code=401, error_type='authentication_error', code='authentication_error')\n" + "APIError(message='x-api-key header is required', endpoint='POST /v1/messages', status_code=401, error_type='authentication_error', code='authentication_error', raw={'type': 'error', 'error': {'type': 'authentication_error', 'message': 'x-api-key header is required'}, 'request_id': 'req_011CZpVwn8ckoA9YzcA7zBDk'})\n" ] } ], @@ -1668,7 +1738,7 @@ "name": "stdout", "output_type": "stream", "text": [ - "APIError(message='anthropic-version: header is required', endpoint='POST /v1/messages', status_code=400, error_type='invalid_request_error', code='invalid_request_error', request_id='req_011CcnV9qGFopMTS8zjXPrZY')\n" + "APIError(message='anthropic-version: header is required', endpoint='POST /v1/messages', status_code=400, error_type='invalid_request_error', code='invalid_request_error', request_id='req_011CeRR61EZtGV3coLiVgJzw', raw={'type': 'error', 'error': {'type': 'invalid_request_error', 'message': 'anthropic-version: header is required'}, 'request_id': 'req_011CeRR61EZtGV3coLiVgJzw'})\n" ] } ], @@ -1938,12 +2008,14 @@ "text/markdown": [ "## batches\n", "\n", - "- batches.list(name, filter, page_size, page_token, return_partial_success): *Lists operations that match the specified filter in the request. If the server doesn't support this method, it returns `UNIMPLEMENTED`.*\n", - "- batches.get(name): *Gets the latest state of a long-running operation. Clients can use this method to poll the operation result at intervals as recommended by the API service.*\n", - "- batches.delete(name): *Deletes a long-running operation. This method indicates that the client is no longer interested in the operation result. It does not cancel the operation. If the server " + "- batches.list(name, filter, page_size, page_token, return_partial_success, access_token, alt, callback, fields, key, oauth_token, pretty_print, quota_user, upload_protocol, upload_type, xgafv): *Lists operations that match the specified filter in the request. If the server doesn't support this method, it returns `UNIMPLEMENTED`.*\n", + "- batches.get(name, access_token, alt, callback, fields, key, oauth_token, pretty_print, quota_user, upload_protocol, upload_type, xgafv): *Gets the latest state of a long-running operation. Clients can use this method to poll the operation result at inte" ], "text/plain": [ - "" + "Markdown(## batches\n", + "\n", + "- batches.list(name, filter, page_size, page_token, return_partial_success, access_token, alt, callback, fields, key, oauth_token, pretty_print, quota_user, upload_protocol, upload_type, xgafv): *Lists operations that match the specified filter in the request. If the server doesn't support this method, it returns `UNIMPLEMENTED`.*\n", + "- batches.get(name, access_token, alt, callback, fields, key, oauth_token, pretty_print, quota_user, upload_protocol, upload_type, xgafv): *Gets the latest state of a long-running operation. Clients can use this method to poll the operation result at inte)" ] }, "execution_count": null,