slot-flight 0.1.0__tar.gz

slot_flight-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Minho Jang
+
+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.

slot_flight-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE
+include README.md
+prune examples
+prune tests
+global-exclude __pycache__ *.py[cod]

slot_flight-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: slot-flight
+Version: 0.1.0
+Summary: Slot-wise LLM generation and server-owned JSON assembly for Python.
+Author: slot-flight contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/miinhho/slot-flight
+Project-URL: Repository, https://github.com/miinhho/slot-flight
+Project-URL: Issues, https://github.com/miinhho/slot-flight/issues
+Keywords: llm,json,streaming,slot-generation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic<3,>=2
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == "langchain"
+Provides-Extra: openai
+Requires-Dist: openai>=1; extra == "openai"
+Provides-Extra: openai-compatible
+Requires-Dist: httpx>=0.28; extra == "openai-compatible"
+Provides-Extra: adapters
+Requires-Dist: httpx>=0.28; extra == "adapters"
+Requires-Dist: langchain-core>=0.3; extra == "adapters"
+Requires-Dist: openai>=1; extra == "adapters"
+Dynamic: license-file
+
+# slot-flight Python
+
+Python SDK for slot-wise LLM value streaming with server-owned JSON assembly.
+
+This package implements the same slot frame protocol used by the TypeScript SDK.
+The core engine is provider-independent, and the public object API is Pydantic
+first. Provider/framework adapters are available for the OpenAI SDK,
+OpenAI-compatible HTTP endpoints, and LangChain. Runnable examples live in
+`examples/`.
+
+Full Python SDK notes live in the
+[Python SDK guide](../../docs/python/README.md).
+
+```py
+import os
+
+from openai import AsyncOpenAI
+from pydantic import BaseModel, Field
+from slot_flight import slot_object
+from slot_flight.adapters.openai import stream_slot_object
+
+
+class Triage(BaseModel):
+    summary: str = Field(description="Write one concise operational summary.")
+    tags: list[str] = Field(description="Write a JSON array of exactly 3 tags.")
+
+
+openai = AsyncOpenAI(
+    api_key=os.getenv("API_KEY"),
+    base_url=os.getenv("API_BASE_URL"),
+)
+
+stream = stream_slot_object(
+    client=openai,
+    model=os.getenv("MODEL", "openai/gpt-oss-20b"),
+    messages=[{"role": "user", "content": "Classify this feedback."}],
+    output=slot_object(Triage),
+)
+
+async for slot in stream.completed_slot_stream():
+    print(slot.slot, slot.value)
+
+result = await stream.final_object()
+```
+
+## Slot Object API
+
+`slot_object()` accepts a Pydantic v2 model. Every generated leaf field must use
+`Field(description=...)`; that description becomes the model-facing instruction
+for the slot.
+
+```py
+class Triage(BaseModel):
+    summary: str = Field(description="Write one concise operational summary.")
+    tags: list[str] = Field(description="Write a JSON array of exactly 3 tags.")
+```
+
+String fields, string enums, and string literals use text slots. Other described
+fields use JSON slots and are parsed before Pydantic validates the value. A
+nested model without its own field description is expanded into nested slots; a
+nested model with a description becomes one JSON slot.
+
+Failed slot validation retries only the failed slots up to `max_retries`:
+
+```py
+output = slot_object(Triage, max_retries=1)
+```
+
+The object stream exposes the same views as the TypeScript SDK, using Python
+method names:
+
+```py
+async for event in stream.slot_event_stream():
+    ...
+
+async for partial in stream.partial_object_stream():
+    ...
+
+async for chunk in stream.to_sse(source="completed"):
+    ...
+
+async for line in stream.to_ndjson(source="events"):
+    ...
+```
+
+`final_object()`, `completed_slot_stream()`, `partial_object_stream()`, and
+`slot_event_stream()` consume one underlying model run. After the run finishes,
+later consumers replay cached events. A second live consumer is rejected while a
+run is still active.
+
+If you already have a slot event stream, wrap it with
+`create_slot_object_event_stream()` to reuse the same object-stream views:
+
+```py
+from slot_flight import create_slot_object_event_stream
+
+stream = create_slot_object_event_stream(existing_events)
+```
+
+## HTTP Streaming
+
+`to_sse()` and `to_ndjson()` are framework-neutral async iterators. In FastAPI or
+Starlette, pass them to `StreamingResponse`:
+
+```py
+from starlette.responses import StreamingResponse
+
+
+async def route():
+    stream = stream_slot_object(...)
+    return StreamingResponse(
+        stream.to_sse(source="completed"),
+        media_type="text/event-stream",
+    )
+```
+
+`source="completed"` emits completed slot updates plus retry/error/done events.
+`source="partial"` emits draft object snapshots. `source="events"` emits the
+low-level slot lifecycle events.
+
+## Examples
+
+```sh
+uv run --extra openai examples/openai_compatible.py
+uv run --extra openai-compatible examples/openai_compatible_httpx.py
+uv run --extra langchain examples/langchain_runnable.py
+```
+
+The OpenAI SDK example and raw OpenAI-compatible HTTP example both work with
+endpoints such as NVIDIA NIM: set `API_KEY`, `API_BASE_URL`, and `MODEL` as
+shown in the root `.env.example`.
+
+## Development
+
+```sh
+uv sync --all-extras --dev
+uv run ruff check .
+uv run ty check
+uv run pytest
+uv build
+```

slot_flight-0.1.0/README.md

@@ -0,0 +1,141 @@
+# slot-flight Python
+
+Python SDK for slot-wise LLM value streaming with server-owned JSON assembly.
+
+This package implements the same slot frame protocol used by the TypeScript SDK.
+The core engine is provider-independent, and the public object API is Pydantic
+first. Provider/framework adapters are available for the OpenAI SDK,
+OpenAI-compatible HTTP endpoints, and LangChain. Runnable examples live in
+`examples/`.
+
+Full Python SDK notes live in the
+[Python SDK guide](../../docs/python/README.md).
+
+```py
+import os
+
+from openai import AsyncOpenAI
+from pydantic import BaseModel, Field
+from slot_flight import slot_object
+from slot_flight.adapters.openai import stream_slot_object
+
+
+class Triage(BaseModel):
+    summary: str = Field(description="Write one concise operational summary.")
+    tags: list[str] = Field(description="Write a JSON array of exactly 3 tags.")
+
+
+openai = AsyncOpenAI(
+    api_key=os.getenv("API_KEY"),
+    base_url=os.getenv("API_BASE_URL"),
+)
+
+stream = stream_slot_object(
+    client=openai,
+    model=os.getenv("MODEL", "openai/gpt-oss-20b"),
+    messages=[{"role": "user", "content": "Classify this feedback."}],
+    output=slot_object(Triage),
+)
+
+async for slot in stream.completed_slot_stream():
+    print(slot.slot, slot.value)
+
+result = await stream.final_object()
+```
+
+## Slot Object API
+
+`slot_object()` accepts a Pydantic v2 model. Every generated leaf field must use
+`Field(description=...)`; that description becomes the model-facing instruction
+for the slot.
+
+```py
+class Triage(BaseModel):
+    summary: str = Field(description="Write one concise operational summary.")
+    tags: list[str] = Field(description="Write a JSON array of exactly 3 tags.")
+```
+
+String fields, string enums, and string literals use text slots. Other described
+fields use JSON slots and are parsed before Pydantic validates the value. A
+nested model without its own field description is expanded into nested slots; a
+nested model with a description becomes one JSON slot.
+
+Failed slot validation retries only the failed slots up to `max_retries`:
+
+```py
+output = slot_object(Triage, max_retries=1)
+```
+
+The object stream exposes the same views as the TypeScript SDK, using Python
+method names:
+
+```py
+async for event in stream.slot_event_stream():
+    ...
+
+async for partial in stream.partial_object_stream():
+    ...
+
+async for chunk in stream.to_sse(source="completed"):
+    ...
+
+async for line in stream.to_ndjson(source="events"):
+    ...
+```
+
+`final_object()`, `completed_slot_stream()`, `partial_object_stream()`, and
+`slot_event_stream()` consume one underlying model run. After the run finishes,
+later consumers replay cached events. A second live consumer is rejected while a
+run is still active.
+
+If you already have a slot event stream, wrap it with
+`create_slot_object_event_stream()` to reuse the same object-stream views:
+
+```py
+from slot_flight import create_slot_object_event_stream
+
+stream = create_slot_object_event_stream(existing_events)
+```
+
+## HTTP Streaming
+
+`to_sse()` and `to_ndjson()` are framework-neutral async iterators. In FastAPI or
+Starlette, pass them to `StreamingResponse`:
+
+```py
+from starlette.responses import StreamingResponse
+
+
+async def route():
+    stream = stream_slot_object(...)
+    return StreamingResponse(
+        stream.to_sse(source="completed"),
+        media_type="text/event-stream",
+    )
+```
+
+`source="completed"` emits completed slot updates plus retry/error/done events.
+`source="partial"` emits draft object snapshots. `source="events"` emits the
+low-level slot lifecycle events.
+
+## Examples
+
+```sh
+uv run --extra openai examples/openai_compatible.py
+uv run --extra openai-compatible examples/openai_compatible_httpx.py
+uv run --extra langchain examples/langchain_runnable.py
+```
+
+The OpenAI SDK example and raw OpenAI-compatible HTTP example both work with
+endpoints such as NVIDIA NIM: set `API_KEY`, `API_BASE_URL`, and `MODEL` as
+shown in the root `.env.example`.
+
+## Development
+
+```sh
+uv sync --all-extras --dev
+uv run ruff check .
+uv run ty check
+uv run pytest
+uv build
+```

slot_flight-0.1.0/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "slot-flight"
+version = "0.1.0"
+description = "Slot-wise LLM generation and server-owned JSON assembly for Python."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "slot-flight contributors" }]
+keywords = ["llm", "json", "streaming", "slot-generation"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed"
+]
+dependencies = [
+  "pydantic>=2,<3"
+]
+
+[project.urls]
+Homepage = "https://github.com/miinhho/slot-flight"
+Repository = "https://github.com/miinhho/slot-flight"
+Issues = "https://github.com/miinhho/slot-flight/issues"
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.3"]
+openai = ["openai>=1"]
+openai-compatible = ["httpx>=0.28"]
+adapters = [
+  "httpx>=0.28",
+  "langchain-core>=0.3",
+  "openai>=1"
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+slot_flight = ["py.typed"]
+
+[dependency-groups]
+dev = [
+  "pytest>=8",
+  "ruff>=0.8",
+  "twine>=6",
+  "ty>=0.0.1a20"
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/slot_flight/prompt.py" = ["E501"]
+
+[tool.ty.environment]
+python-version = "3.10"

slot_flight-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

slot_flight-0.1.0/src/slot_flight/__init__.py

@@ -0,0 +1,48 @@
+from .errors import (
+    SlotFlightConfigurationError,
+    SlotFlightError,
+    SlotFlightJsonParseError,
+    SlotFlightSlotProtocolError,
+    SlotFlightStreamError,
+    SlotFlightValidationError,
+)
+from .slot.execution import SlotFlight, slot_flight
+from .slot.object import (
+    CompletedSlot,
+    SlotObjectEventSource,
+    SlotObjectOutput,
+    SlotObjectStream,
+    SlotObjectStreamFormat,
+    SlotObjectStreamSource,
+    create_slot_object_event_stream,
+    create_slot_object_stream,
+    slot_object,
+)
+from .types import (
+    SlotDefinition,
+    SlotFlightRequest,
+    SlotFrameRequest,
+)
+
+__all__ = [
+    "SlotDefinition",
+    "SlotFlight",
+    "SlotFlightConfigurationError",
+    "SlotFlightError",
+    "SlotFlightJsonParseError",
+    "SlotFlightRequest",
+    "SlotFlightSlotProtocolError",
+    "SlotFlightStreamError",
+    "SlotFlightValidationError",
+    "SlotFrameRequest",
+    "SlotObjectEventSource",
+    "SlotObjectOutput",
+    "SlotObjectStream",
+    "SlotObjectStreamFormat",
+    "SlotObjectStreamSource",
+    "CompletedSlot",
+    "create_slot_object_event_stream",
+    "create_slot_object_stream",
+    "slot_flight",
+    "slot_object",
+]

slot_flight-0.1.0/src/slot_flight/_streams.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import AsyncIterable, AsyncIterator, Iterable
+from typing import Any, TypeVar, cast
+
+T = TypeVar("T")
+
+
+async def iterate_stream(stream: Any, *, error_message: str) -> AsyncIterator[T]:
+    try:
+        if hasattr(stream, "__aiter__"):
+            async for item in cast(AsyncIterable[T], stream):
+                yield item
+            return
+
+        if isinstance(stream, Iterable):
+            for item in cast(Iterable[T], stream):
+                yield item
+            return
+
+        raise TypeError(error_message)
+    finally:
+        await close_stream(stream)
+
+
+async def close_stream(stream: Any) -> None:
+    close = getattr(stream, "aclose", None)
+    if callable(close):
+        result = close()
+        if inspect.isawaitable(result):
+            await result
+        return
+
+    close = getattr(stream, "close", None)
+    if callable(close):
+        result = close()
+        if inspect.isawaitable(result):
+            await result

slot_flight-0.1.0/src/slot_flight/adapters/__init__.py

@@ -0,0 +1 @@
+__all__: list[str] = []

slot_flight-0.1.0/src/slot_flight/adapters/langchain.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from slot_flight._streams import close_stream, iterate_stream
+from slot_flight.slot.object import (
+    SlotObjectOutput,
+    SlotObjectStream,
+    create_slot_object_stream,
+)
+from slot_flight.types import SlotFlightRequest
+
+
+def stream_slot_object(
+    *,
+    runnable: Any,
+    messages: Sequence[Any],
+    output: SlotObjectOutput,
+    **params: Any,
+) -> SlotObjectStream:
+    async def generate(request: SlotFlightRequest):
+        request_messages = [*messages, ("human", request.prompt)]
+
+        if hasattr(runnable, "astream"):
+            stream = runnable.astream(request_messages, **params)
+            chunks = iterate_stream(
+                stream,
+                error_message="LangChain stream must be iterable or async iterable.",
+            )
+            try:
+                async for chunk in chunks:
+                    text = _chunk_text(chunk)
+                    if text:
+                        yield text
+            finally:
+                await close_stream(chunks)
+            return
+
+        if hasattr(runnable, "stream"):
+            stream = runnable.stream(request_messages, **params)
+            chunks = iterate_stream(
+                stream,
+                error_message="LangChain stream must be iterable or async iterable.",
+            )
+            try:
+                async for chunk in chunks:
+                    text = _chunk_text(chunk)
+                    if text:
+                        yield text
+            finally:
+                await close_stream(chunks)
+            return
+
+        raise TypeError("LangChain runnable must expose stream() or astream().")
+
+    return create_slot_object_stream(output=output, generate=generate)
+
+
+def _chunk_text(chunk: Any) -> str:
+    if isinstance(chunk, str):
+        return chunk
+
+    content = getattr(chunk, "content", None)
+    text = _content_text(content)
+    if text:
+        return text
+
+    if isinstance(chunk, dict):
+        return _content_text(chunk.get("content", ""))
+    return ""
+
+
+def _content_text(content: Any) -> str:
+    if isinstance(content, str):
+        return content
+
+    if isinstance(content, list):
+        return "".join(_content_part_text(part) for part in content)
+
+    return ""
+
+
+def _content_part_text(part: Any) -> str:
+    if isinstance(part, str):
+        return part
+
+    if isinstance(part, dict):
+        text = part.get("text", "")
+        return text if isinstance(text, str) else ""
+
+    text = getattr(part, "text", "")
+    return text if isinstance(text, str) else ""

slot_flight-0.1.0/src/slot_flight/adapters/openai.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import Sequence
+from typing import Any
+
+from slot_flight._streams import close_stream, iterate_stream
+from slot_flight.slot.object import (
+    SlotObjectOutput,
+    SlotObjectStream,
+    create_slot_object_stream,
+)
+from slot_flight.types import SlotFlightRequest
+
+
+def stream_slot_object(
+    *,
+    client: Any,
+    model: str,
+    messages: Sequence[dict[str, Any]],
+    output: SlotObjectOutput,
+    **params: Any,
+) -> SlotObjectStream:
+    async def generate(request: SlotFlightRequest):
+        request_messages = [
+            *messages,
+            {
+                "role": "user",
+                "content": request.prompt,
+            },
+        ]
+        stream = client.chat.completions.create(
+            model=model,
+            messages=request_messages,
+            stream=True,
+            **params,
+        )
+        if inspect.isawaitable(stream):
+            stream = await stream
+
+        chunks = iterate_stream(
+            stream,
+            error_message="OpenAI stream must be iterable or async iterable.",
+        )
+        try:
+            async for chunk in chunks:
+                text = _chunk_text(chunk)
+                if text:
+                    yield text
+        finally:
+            await close_stream(chunks)
+
+    return create_slot_object_stream(output=output, generate=generate)
+
+
+def _chunk_text(chunk: Any) -> str:
+    choices = _get(chunk, "choices", [])
+    if not choices:
+        return ""
+    delta = _get(choices[0], "delta", None)
+    content = _get(delta, "content", "")
+    return content if isinstance(content, str) else ""
+
+
+def _get(value: Any, key: str, default: Any) -> Any:
+    if isinstance(value, dict):
+        return value.get(key, default)
+    return getattr(value, key, default)