vikky 0.1.0__tar.gz

vikky-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VSP AI & Robotics
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vikky-0.1.0/PKG-INFO

@@ -0,0 +1,326 @@
+Metadata-Version: 2.4
+Name: vikky
+Version: 0.1.0
+Summary: Python SDK for Vikky Platform: chat, vision, speech, embeddings, images and more with one key.
+Keywords: vikky,vikkyverse,ai,llm,sdk,api
+Author: VSP AI & Robotics
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Dist: openai>=1.55.3
+Requires-Python: >=3.9
+Project-URL: Homepage, https://vikkyverse.com
+Project-URL: Documentation, https://vikkyverse.com/docs
+Project-URL: Get an API key, https://vikkyverse.com/platform
+Description-Content-Type: text/markdown
+
+# vikky
+
+Python client for **Vikky**, VSP's AI API gateway. Vikky speaks the OpenAI API,
+so this package is a thin wrapper over the official `openai` package: anything
+in the OpenAI Python docs works here too.
+
+## Install
+
+```bash
+pip install vikky
+```
+
+In Colab or Jupyter, use `%pip install vikky`.
+
+## Get a key
+
+Sign in to the Vikky console at https://vikkyverse.com/platform and create an API key. Keep it secret: anyone with
+the key spends your quota.
+
+## Set VIKKY_API_KEY
+
+On your laptop:
+
+```bash
+export VIKKY_API_KEY="your-key"
+```
+
+In Google Colab: click the key icon in the left sidebar, add a secret named
+`VIKKY_API_KEY`, turn on "Notebook access", then run:
+
+```python
+import os
+from google.colab import userdata
+
+os.environ["VIKKY_API_KEY"] = userdata.get("VIKKY_API_KEY")
+```
+
+Never paste the key into a notebook cell you might share.
+
+## First call (JSON out)
+
+```python
+import json
+from vikky import Vikky
+
+client = Vikky()  # reads VIKKY_API_KEY
+
+resp = client.chat.completions.create(
+    model="vikky-chat",
+    messages=[
+        {"role": "system", "content": "Reply in JSON."},
+        {"role": "user", "content": 'List 3 planets as {"planets": [...]}'},
+    ],
+    response_format={"type": "json_object"},
+)
+data = json.loads(resp.choices[0].message.content)
+print(data["planets"])
+```
+
+JSON mode works best when your messages say "JSON" and show the shape you want.
+
+## Streaming
+
+```python
+stream = client.chat.completions.create(
+    model="vikky-chat",
+    messages=[{"role": "user", "content": "Explain PID control in 3 lines."}],
+    stream=True,
+)
+for chunk in stream:
+    if chunk.choices:
+        print(chunk.choices[0].delta.content or "", end="", flush=True)
+```
+
+## Models
+
+| Model | What it does | Call it with |
+|---|---|---|
+| `vikky-chat` | chat, JSON output, tool calling | `chat.completions.create`, or `responses.create` |
+| `vikky-vision` | chat that also takes images | `chat.completions.create` with an `image_url` part |
+| `vikky-embed` | embeddings | `embeddings.create` |
+| `vikky-transcribe` | audio to text | `audio.transcriptions.create` |
+| `vikky-speech` | text to audio | `audio.speech.create` |
+| `vikky-image` | image generation and editing | `images.generate`, `images.edit` |
+| `vikky-video` | video generation, async | `videos.create_and_poll` |
+| `vikky-rerank` | rank documents against a query | `rerank` |
+| `vikky-ocr` | text out of a document | `ocr` |
+| `vikky-moderate` | content moderation | `moderations.create` |
+
+Every row except the last two is a method the `openai` package already has, so
+the OpenAI Python docs apply unchanged. `rerank` and `ocr` are not OpenAI
+routes: they are the only two methods this package adds, and they return a
+plain dict instead of a typed object.
+
+## Tool calling
+
+```python
+resp = client.chat.completions.create(
+    model="vikky-chat",
+    messages=[{"role": "user", "content": "Weather in Hyderabad?"}],
+    tools=[{"type": "function", "function": {
+        "name": "get_weather",
+        "parameters": {"type": "object", "properties": {"city": {"type": "string"}}},
+    }}],
+)
+call = resp.choices[0].message.tool_calls[0]
+print(call.function.name, call.function.arguments)
+```
+
+## Responses API
+
+```python
+resp = client.responses.create(model="vikky-chat", input="Say hello.")
+print(resp.output_text)
+```
+
+## Vision
+
+```python
+resp = client.chat.completions.create(
+    model="vikky-vision",
+    messages=[{"role": "user", "content": [
+        {"type": "text", "text": "What is in this picture?"},
+        {"type": "image_url", "image_url": {"url": "https://example.com/arm.jpg"}},
+    ]}],
+)
+print(resp.choices[0].message.content)
+```
+
+For a local image, pass a data URL as the `url`:
+
+```python
+import base64, pathlib
+
+raw = base64.b64encode(pathlib.Path("arm.png").read_bytes()).decode()
+url = f"data:image/png;base64,{raw}"
+```
+
+## Embeddings
+
+```python
+resp = client.embeddings.create(model="vikky-embed", input=["robot arm", "pizza"])
+arm, pizza = (d.embedding for d in resp.data)
+print(len(arm), len(pizza))
+```
+
+Pass a list to embed a batch in one call. Results come back in the order you
+sent them, and `d.index` tells you which input each vector belongs to.
+
+## Audio to text
+
+```python
+with open("meeting.m4a", "rb") as f:
+    resp = client.audio.transcriptions.create(model="vikky-transcribe", file=f)
+print(resp.text)
+```
+
+## Text to audio
+
+```python
+resp = client.audio.speech.create(
+    model="vikky-speech",
+    voice="alloy",
+    input="The arm is homed and ready.",
+)
+resp.write_to_file("ready.mp3")
+```
+
+## Images
+
+```python
+resp = client.images.generate(model="vikky-image", prompt="a blue robot arm on a bench", n=1)
+item = resp.data[0]
+print(item.url or "returned as base64")  # either one, see "Saving generated media"
+
+with open("arm.png", "rb") as f:
+    edited = client.images.edit(model="vikky-image", image=f, prompt="make the bench wooden")
+```
+
+## Video
+
+Video generation takes minutes, so it is a job, not a call. Submit it, wait for
+it, then download it. Keep the id `create` gave you and download with that one.
+
+```python
+job = client.videos.create(model="vikky-video", prompt="a robot arm picking up a cube")
+done = client.videos.poll(job.id, poll_interval_ms=5000)
+assert done.status == "completed", done.error
+client.videos.download_content(job.id).write_to_file("clip.mp4")
+```
+
+`client.videos.retrieve(job.id)` is the single-shot version of `poll`, if you
+want to show `video.progress` in your own loop. Do not use
+`videos.create_and_poll`: it only returns the polled job, and Vikky's polled id
+cannot be downloaded from.
+
+## Saving generated media
+
+An image comes back as either a URL or base64, depending on what you asked
+for. Audio and video come back as a binary response with `write_to_file`.
+
+```python
+import base64, pathlib, urllib.request
+
+item = client.images.generate(model="vikky-image", prompt="a blue cube").data[0]
+if item.b64_json:
+    pathlib.Path("cube.png").write_bytes(base64.b64decode(item.b64_json))
+else:
+    with urllib.request.urlopen(item.url) as r:
+        pathlib.Path("cube.png").write_bytes(r.read())
+```
+
+Ask for `response_format="b64_json"` and you never have to fetch a URL at all.
+
+**A generated file's URL is temporary.** Download it in the same run that
+created it. Do not store the URL in a database or a notebook output and expect
+it to still work tomorrow.
+
+## Rerank
+
+```python
+resp = client.rerank(
+    query="how do I reset the arm?",
+    documents=[
+        "Press the red button to reset the arm.",
+        "Our office is in Hyderabad.",
+    ],
+    top_n=1,
+)
+for r in resp["results"]:
+    print(r["index"], r["relevance_score"])
+```
+
+Results come back best first. `r["index"]` points back into the `documents`
+list you sent.
+
+## OCR
+
+```python
+resp = client.ocr(document={"type": "document_url", "document_url": "https://example.com/invoice.pdf"})
+for page in resp["pages"]:
+    print(page["markdown"])
+```
+
+For an image instead of a PDF, send
+`{"type": "image_url", "image_url": "https://..."}`. A data URL works too.
+
+## Moderation
+
+```python
+resp = client.moderations.create(model="vikky-moderate", input="Some user text.")
+result = resp.results[0]
+print(result.flagged, [name for name, hit in result.categories if hit])
+```
+
+## Async
+
+```python
+import asyncio
+from vikky import AsyncVikky
+
+async def main():
+    client = AsyncVikky()
+    resp = await client.chat.completions.create(
+        model="vikky-chat",
+        messages=[{"role": "user", "content": "Say hello."}],
+    )
+    print(resp.choices[0].message.content)
+
+asyncio.run(main())  # in Colab or Jupyter, use: await main()
+```
+
+Every model above works on `AsyncVikky`, `rerank` and `ocr` included: same
+arguments, awaited.
+
+## Environment variables
+
+| Variable | Required | Default |
+|---|---|---|
+| `VIKKY_API_KEY` | yes | none. `OPENAI_API_KEY` is never used. |
+| `VIKKY_BASE_URL` | no | `https://api.vikkyverse.com/v1` |
+
+Arguments win over environment: `Vikky(api_key=..., base_url=...)`. Every other
+argument (`timeout`, `max_retries`, ...) goes straight to `openai.OpenAI`.
+A missing key raises `vikky.VikkyError`.
+
+## If Vikky is down
+
+Write lab code so the model name comes from the environment:
+
+```python
+import os
+from vikky import Vikky
+
+MODEL = os.environ.get("VIKKY_MODEL", "vikky-chat")
+client = Vikky()
+resp = client.chat.completions.create(model=MODEL, messages=[...])
+```
+
+Then a trainer can set `VIKKY_BASE_URL`, `VIKKY_API_KEY` and `VIKKY_MODEL` to
+any other OpenAI-compatible endpoint, and the notebook runs unchanged.
+
+## License
+
+MIT

vikky-0.1.0/README.md

@@ -0,0 +1,305 @@
+# vikky
+
+Python client for **Vikky**, VSP's AI API gateway. Vikky speaks the OpenAI API,
+so this package is a thin wrapper over the official `openai` package: anything
+in the OpenAI Python docs works here too.
+
+## Install
+
+```bash
+pip install vikky
+```
+
+In Colab or Jupyter, use `%pip install vikky`.
+
+## Get a key
+
+Sign in to the Vikky console at https://vikkyverse.com/platform and create an API key. Keep it secret: anyone with
+the key spends your quota.
+
+## Set VIKKY_API_KEY
+
+On your laptop:
+
+```bash
+export VIKKY_API_KEY="your-key"
+```
+
+In Google Colab: click the key icon in the left sidebar, add a secret named
+`VIKKY_API_KEY`, turn on "Notebook access", then run:
+
+```python
+import os
+from google.colab import userdata
+
+os.environ["VIKKY_API_KEY"] = userdata.get("VIKKY_API_KEY")
+```
+
+Never paste the key into a notebook cell you might share.
+
+## First call (JSON out)
+
+```python
+import json
+from vikky import Vikky
+
+client = Vikky()  # reads VIKKY_API_KEY
+
+resp = client.chat.completions.create(
+    model="vikky-chat",
+    messages=[
+        {"role": "system", "content": "Reply in JSON."},
+        {"role": "user", "content": 'List 3 planets as {"planets": [...]}'},
+    ],
+    response_format={"type": "json_object"},
+)
+data = json.loads(resp.choices[0].message.content)
+print(data["planets"])
+```
+
+JSON mode works best when your messages say "JSON" and show the shape you want.
+
+## Streaming
+
+```python
+stream = client.chat.completions.create(
+    model="vikky-chat",
+    messages=[{"role": "user", "content": "Explain PID control in 3 lines."}],
+    stream=True,
+)
+for chunk in stream:
+    if chunk.choices:
+        print(chunk.choices[0].delta.content or "", end="", flush=True)
+```
+
+## Models
+
+| Model | What it does | Call it with |
+|---|---|---|
+| `vikky-chat` | chat, JSON output, tool calling | `chat.completions.create`, or `responses.create` |
+| `vikky-vision` | chat that also takes images | `chat.completions.create` with an `image_url` part |
+| `vikky-embed` | embeddings | `embeddings.create` |
+| `vikky-transcribe` | audio to text | `audio.transcriptions.create` |
+| `vikky-speech` | text to audio | `audio.speech.create` |
+| `vikky-image` | image generation and editing | `images.generate`, `images.edit` |
+| `vikky-video` | video generation, async | `videos.create_and_poll` |
+| `vikky-rerank` | rank documents against a query | `rerank` |
+| `vikky-ocr` | text out of a document | `ocr` |
+| `vikky-moderate` | content moderation | `moderations.create` |
+
+Every row except the last two is a method the `openai` package already has, so
+the OpenAI Python docs apply unchanged. `rerank` and `ocr` are not OpenAI
+routes: they are the only two methods this package adds, and they return a
+plain dict instead of a typed object.
+
+## Tool calling
+
+```python
+resp = client.chat.completions.create(
+    model="vikky-chat",
+    messages=[{"role": "user", "content": "Weather in Hyderabad?"}],
+    tools=[{"type": "function", "function": {
+        "name": "get_weather",
+        "parameters": {"type": "object", "properties": {"city": {"type": "string"}}},
+    }}],
+)
+call = resp.choices[0].message.tool_calls[0]
+print(call.function.name, call.function.arguments)
+```
+
+## Responses API
+
+```python
+resp = client.responses.create(model="vikky-chat", input="Say hello.")
+print(resp.output_text)
+```
+
+## Vision
+
+```python
+resp = client.chat.completions.create(
+    model="vikky-vision",
+    messages=[{"role": "user", "content": [
+        {"type": "text", "text": "What is in this picture?"},
+        {"type": "image_url", "image_url": {"url": "https://example.com/arm.jpg"}},
+    ]}],
+)
+print(resp.choices[0].message.content)
+```
+
+For a local image, pass a data URL as the `url`:
+
+```python
+import base64, pathlib
+
+raw = base64.b64encode(pathlib.Path("arm.png").read_bytes()).decode()
+url = f"data:image/png;base64,{raw}"
+```
+
+## Embeddings
+
+```python
+resp = client.embeddings.create(model="vikky-embed", input=["robot arm", "pizza"])
+arm, pizza = (d.embedding for d in resp.data)
+print(len(arm), len(pizza))
+```
+
+Pass a list to embed a batch in one call. Results come back in the order you
+sent them, and `d.index` tells you which input each vector belongs to.
+
+## Audio to text
+
+```python
+with open("meeting.m4a", "rb") as f:
+    resp = client.audio.transcriptions.create(model="vikky-transcribe", file=f)
+print(resp.text)
+```
+
+## Text to audio
+
+```python
+resp = client.audio.speech.create(
+    model="vikky-speech",
+    voice="alloy",
+    input="The arm is homed and ready.",
+)
+resp.write_to_file("ready.mp3")
+```
+
+## Images
+
+```python
+resp = client.images.generate(model="vikky-image", prompt="a blue robot arm on a bench", n=1)
+item = resp.data[0]
+print(item.url or "returned as base64")  # either one, see "Saving generated media"
+
+with open("arm.png", "rb") as f:
+    edited = client.images.edit(model="vikky-image", image=f, prompt="make the bench wooden")
+```
+
+## Video
+
+Video generation takes minutes, so it is a job, not a call. Submit it, wait for
+it, then download it. Keep the id `create` gave you and download with that one.
+
+```python
+job = client.videos.create(model="vikky-video", prompt="a robot arm picking up a cube")
+done = client.videos.poll(job.id, poll_interval_ms=5000)
+assert done.status == "completed", done.error
+client.videos.download_content(job.id).write_to_file("clip.mp4")
+```
+
+`client.videos.retrieve(job.id)` is the single-shot version of `poll`, if you
+want to show `video.progress` in your own loop. Do not use
+`videos.create_and_poll`: it only returns the polled job, and Vikky's polled id
+cannot be downloaded from.
+
+## Saving generated media
+
+An image comes back as either a URL or base64, depending on what you asked
+for. Audio and video come back as a binary response with `write_to_file`.
+
+```python
+import base64, pathlib, urllib.request
+
+item = client.images.generate(model="vikky-image", prompt="a blue cube").data[0]
+if item.b64_json:
+    pathlib.Path("cube.png").write_bytes(base64.b64decode(item.b64_json))
+else:
+    with urllib.request.urlopen(item.url) as r:
+        pathlib.Path("cube.png").write_bytes(r.read())
+```
+
+Ask for `response_format="b64_json"` and you never have to fetch a URL at all.
+
+**A generated file's URL is temporary.** Download it in the same run that
+created it. Do not store the URL in a database or a notebook output and expect
+it to still work tomorrow.
+
+## Rerank
+
+```python
+resp = client.rerank(
+    query="how do I reset the arm?",
+    documents=[
+        "Press the red button to reset the arm.",
+        "Our office is in Hyderabad.",
+    ],
+    top_n=1,
+)
+for r in resp["results"]:
+    print(r["index"], r["relevance_score"])
+```
+
+Results come back best first. `r["index"]` points back into the `documents`
+list you sent.
+
+## OCR
+
+```python
+resp = client.ocr(document={"type": "document_url", "document_url": "https://example.com/invoice.pdf"})
+for page in resp["pages"]:
+    print(page["markdown"])
+```
+
+For an image instead of a PDF, send
+`{"type": "image_url", "image_url": "https://..."}`. A data URL works too.
+
+## Moderation
+
+```python
+resp = client.moderations.create(model="vikky-moderate", input="Some user text.")
+result = resp.results[0]
+print(result.flagged, [name for name, hit in result.categories if hit])
+```
+
+## Async
+
+```python
+import asyncio
+from vikky import AsyncVikky
+
+async def main():
+    client = AsyncVikky()
+    resp = await client.chat.completions.create(
+        model="vikky-chat",
+        messages=[{"role": "user", "content": "Say hello."}],
+    )
+    print(resp.choices[0].message.content)
+
+asyncio.run(main())  # in Colab or Jupyter, use: await main()
+```
+
+Every model above works on `AsyncVikky`, `rerank` and `ocr` included: same
+arguments, awaited.
+
+## Environment variables
+
+| Variable | Required | Default |
+|---|---|---|
+| `VIKKY_API_KEY` | yes | none. `OPENAI_API_KEY` is never used. |
+| `VIKKY_BASE_URL` | no | `https://api.vikkyverse.com/v1` |
+
+Arguments win over environment: `Vikky(api_key=..., base_url=...)`. Every other
+argument (`timeout`, `max_retries`, ...) goes straight to `openai.OpenAI`.
+A missing key raises `vikky.VikkyError`.
+
+## If Vikky is down
+
+Write lab code so the model name comes from the environment:
+
+```python
+import os
+from vikky import Vikky
+
+MODEL = os.environ.get("VIKKY_MODEL", "vikky-chat")
+client = Vikky()
+resp = client.chat.completions.create(model=MODEL, messages=[...])
+```
+
+Then a trainer can set `VIKKY_BASE_URL`, `VIKKY_API_KEY` and `VIKKY_MODEL` to
+any other OpenAI-compatible endpoint, and the notebook runs unchanged.
+
+## License
+
+MIT

vikky-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "vikky"
+version = "0.1.0"
+description = "Python SDK for Vikky Platform: chat, vision, speech, embeddings, images and more with one key."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "VSP AI & Robotics" }]
+requires-python = ">=3.9"
+# 1.55.3: first openai release that works with httpx 0.28 (older ones crash on `proxies`).
+dependencies = ["openai>=1.55.3"]
+keywords = ["vikky", "vikkyverse", "ai", "llm", "sdk", "api"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://vikkyverse.com"
+Documentation = "https://vikkyverse.com/docs"
+"Get an API key" = "https://vikkyverse.com/platform"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["uv_build>=0.11.14,<0.12.0"]
+build-backend = "uv_build"

vikky-0.1.0/src/vikky/__init__.py

@@ -0,0 +1,98 @@
+"""Python client for Vikky, VSP's OpenAI-compatible AI API gateway.
+
+A thin wrapper over the official ``openai`` package: only the API key and
+base URL defaults differ. Everything else is plain ``openai``.
+
+Chat, vision, embeddings, audio, images, video and moderation all go through
+the methods ``openai`` already has. The two exceptions are ``rerank`` and
+``ocr``: Vikky serves those, the OpenAI API does not, so they are the only
+methods this package adds.
+"""
+
+from __future__ import annotations
+
+import os
+from importlib.metadata import version
+from typing import TYPE_CHECKING, Any, Dict, cast
+
+import openai
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+__version__ = version("vikky")
+__all__ = ["DEFAULT_BASE_URL", "AsyncVikky", "Vikky", "VikkyError", "__version__"]
+
+DEFAULT_BASE_URL = "https://api.vikkyverse.com/v1"
+
+
+class VikkyError(openai.OpenAIError):
+    """Raised when a Vikky client cannot be configured."""
+
+
+def _resolve(api_key, base_url):
+    # Never fall back to OPENAI_API_KEY: a student's OpenAI key must not go to Vikky.
+    api_key = api_key or os.environ.get("VIKKY_API_KEY")
+    if not api_key:
+        raise VikkyError("No Vikky API key. Set VIKKY_API_KEY or pass api_key=...")
+    return api_key, base_url or os.environ.get("VIKKY_BASE_URL") or DEFAULT_BASE_URL
+
+
+# /rerank and /ocr are not OpenAI routes, so openai has no method for them and no
+# response model to parse them into. cast_to=object is openai's way of saying "give
+# me the parsed JSON": these two return a plain dict, not a pydantic object.
+# Everything else Vikky serves is a real OpenAI route and is not wrapped here.
+
+
+class Vikky(openai.OpenAI):
+    """``openai.OpenAI`` pointed at Vikky."""
+
+    def __init__(self, *, api_key: str | None = None, base_url: str | None = None, **kwargs):
+        api_key, base_url = _resolve(api_key, base_url)
+        super().__init__(api_key=api_key, base_url=base_url, **kwargs)
+
+    def rerank(
+        self,
+        *,
+        query: str,
+        documents: Sequence[str],
+        model: str = "vikky-rerank",
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        """Score documents against a query. ``POST /v1/rerank``, Cohere-shaped."""
+        body = {"model": model, "query": query, "documents": list(documents), **kwargs}
+        return cast("Dict[str, Any]", self.post("/rerank", body=body, cast_to=object))
+
+    def ocr(
+        self, *, document: Dict[str, Any], model: str = "vikky-ocr", **kwargs: Any
+    ) -> Dict[str, Any]:
+        """Read text out of a document or image. ``POST /v1/ocr``."""
+        body = {"model": model, "document": document, **kwargs}
+        return cast("Dict[str, Any]", self.post("/ocr", body=body, cast_to=object))
+
+
+class AsyncVikky(openai.AsyncOpenAI):
+    """``openai.AsyncOpenAI`` pointed at Vikky."""
+
+    def __init__(self, *, api_key: str | None = None, base_url: str | None = None, **kwargs):
+        api_key, base_url = _resolve(api_key, base_url)
+        super().__init__(api_key=api_key, base_url=base_url, **kwargs)
+
+    async def rerank(
+        self,
+        *,
+        query: str,
+        documents: Sequence[str],
+        model: str = "vikky-rerank",
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        """Score documents against a query. ``POST /v1/rerank``, Cohere-shaped."""
+        body = {"model": model, "query": query, "documents": list(documents), **kwargs}
+        return cast("Dict[str, Any]", await self.post("/rerank", body=body, cast_to=object))
+
+    async def ocr(
+        self, *, document: Dict[str, Any], model: str = "vikky-ocr", **kwargs: Any
+    ) -> Dict[str, Any]:
+        """Read text out of a document or image. ``POST /v1/ocr``."""
+        body = {"model": model, "document": document, **kwargs}
+        return cast("Dict[str, Any]", await self.post("/ocr", body=body, cast_to=object))