laiya 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 665e132b315d14e0d867411d06e49c015ed8bfe18f50e3ee15623eee73a90e6e
+  data.tar.gz: 693d030853123c19d1dda07fda06fac7d6c6b8a8d4b9db7a488cbda3e8ef2add
+SHA512:
+  metadata.gz: 6bb1a3cc19e46eaf6908343327edeb7c4af1867b07016962b4a6a70c22d7f31e44aa3bdf644f6a26ad2ed4d152dfe041f3d416a912aea00005076f988f60c198
+  data.tar.gz: '015801fda685fe3fc0e3fe1d792784fdd4aaa6255e04d6e1d0ea29dc72b5c4360d513834e5681d4ca3b4092067231548e43bf87773b0066930ab4677bdaeac34'

data/bin/laiya

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "async/service"
+require_relative "../lib/laiya/environment/application"
+
+ARGV.each do |path|
+	require(path)
+end
+
+configuration = Async::Service::Configuration.build do
+	service "laiya" do
+		include Laiya::Environment::Application
+	end
+end
+
+Async::Service::Controller.run(configuration)

data/context/chatgpt-codex.md

@@ -0,0 +1,43 @@
+# ChatGPT Codex Provider
+
+This guide explains how to run the experimental Codex provider with a ChatGPT login while keeping tool execution on the client.
+
+## Authentication and Trust
+
+The Codex provider reads ChatGPT credentials from
+`CODEX_HOME/auth.json` (default `~/.codex/auth.json`) and refreshes tokens when
+needed. If the Codex CLI uses an OS keyring, configure file-backed credentials
+and run `codex login`:
+
+```toml
+cli_auth_credentials_store = "file"
+```
+
+Treat `auth.json` as a password. This provider calls the Codex-specific backend,
+not the public OpenAI Platform API. It is experimental and intended for a
+trusted, single-user service. Do not expose it to the public internet or an
+untrusted multi-user environment.
+
+## Start the Example
+
+From the Laiya repository root:
+
+```sh
+export LAIYA_API_KEY="$(openssl rand -hex 32)"
+bundle exec ruby examples/chatgpt/service.rb
+```
+
+The example binds to `127.0.0.1:9293`. It requires the client to send the
+separate `LAIYA_API_KEY` as a Bearer token. For remote clients, use TLS and a
+private access-controlled network. See the [example files](https://github.com/socketry/laiya/tree/main/examples/chatgpt).
+
+## Client-Owned Tool Execution
+
+Use `POST /v1/responses` for tool calling. Laiya preserves the Codex Responses
+stream and response items. The client executes a returned function call and
+sends its `function_call_output` back in the next request. Since Codex is used
+statelessly, send the full input history, including the previous response's
+reasoning and function-call items; `previous_response_id` is not supported.
+
+The text-only `POST /v1/chat/completions` adapter rejects tool-enabled requests
+so it cannot silently lose Codex reasoning state.

data/context/getting-started.md

@@ -0,0 +1,49 @@
+# Getting Started
+
+This guide explains how to install Laiya, configure a provider, and make an OpenAI-compatible request.
+
+## Installation
+
+Add Laiya to your application:
+
+```sh
+bundle add laiya
+```
+
+## Configure a Provider
+
+Laiya's Ruby API uses a `Laiya::Configuration` to connect model IDs to
+providers. For an OpenAI Platform API key:
+
+```ruby
+require "laiya"
+
+configuration = Laiya::Configuration.build do |builder|
+	builder.provider :openai, Laiya::Provider::OpenAI.new(
+		api_key: ENV.fetch("OPENAI_API_KEY")
+	)
+	builder.model "gpt-4.1-mini", provider: :openai
+	builder.default_provider :openai
+end
+
+application = Laiya::Web::Application.new(configuration: configuration)
+```
+
+The provider forwards `Protocol::HTTP::Request` and `Protocol::HTTP::Response`
+objects using `Async::HTTP`. It does not parse OpenAI request or response bodies
+in the direct proxy path.
+
+For Ollama and multi-provider setups, see [Providers and Models](../providers-and-models/).
+
+## Run the API Service
+
+For a local OpenAI API proxy, set the API key and start Laiya:
+
+```sh
+export OPENAI_API_KEY="..."
+bundle exec bin/laiya
+```
+
+The service listens on `http://localhost:9292` by default. Configure `LAIYA_URL`
+to change the endpoint. See [HTTP API](../http-api/) for supported routes and
+streaming behavior.

data/context/http-api.md

@@ -0,0 +1,49 @@
+# HTTP API
+
+This guide explains how Laiya's OpenAI-compatible HTTP API handles routing, proxying, and streaming.
+
+## Run the Async Service
+
+Laiya runs directly on `Async::HTTP::Server` under `Async::Service`; it does not
+use Rack:
+
+```sh
+bundle exec bin/laiya
+```
+
+The default service listens on `http://localhost:9292`. `LAIYA_URL` configures
+the endpoint. `bin/laiya` loads optional Ruby configuration paths supplied on
+the command line before starting the service.
+
+## Endpoints
+
+The API accepts OpenAI-compatible `Protocol::HTTP::Request` objects and returns
+`Protocol::HTTP::Response` objects. Supported common routes include:
+
+- `GET /v1/models`
+- `POST /v1/chat/completions`
+- `POST /v1/responses` when the configured provider supports it
+- Other OpenAI-compatible paths are forwarded to the selected provider.
+
+Configured model routes produce a Laiya model catalog. When a provider is the
+default and no model catalog is configured, `GET /v1/models` is forwarded
+upstream. See [Providers and Models](../providers-and-models/) for discovery.
+
+## Proxy and Model Routing
+
+The built-in OpenAI provider is a direct HTTP proxy. It forwards the method,
+path, headers, and request body, replacing authorization with its configured
+upstream key and filtering hop-by-hop headers. It returns the upstream response
+without parsing its body.
+
+When a model route or discovery source is configured, Laiya buffers and rewinds
+request bodies for known JSON completion endpoints to read the `model` field.
+It forwards the original body unchanged. Streaming response bodies are not
+buffered by the router.
+
+## Streaming
+
+OpenAI-compatible upstream SSE responses pass through unchanged. Translating
+providers may adapt streaming formats. The Codex Responses endpoint passes
+native Responses SSE through, including tool-call events; Laiya does not execute
+client tools.

data/context/index.yaml

@@ -0,0 +1,26 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: An OpenAI-compatible HTTP API and provider proxy
+metadata:
+  bug_tracker_uri: https://github.com/socketry/laiya/issues
+  changelog_uri: https://github.com/socketry/laiya/blob/main/releases.md
+  documentation_uri: https://socketry.github.io/laiya/
+  source_code_uri: https://github.com/socketry/laiya.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to install Laiya, configure a provider, and
+    make an OpenAI-compatible request.
+- path: providers-and-models.md
+  title: Providers and Models
+  description: This guide explains how to route model IDs to providers and when to
+    discover a provider's model catalog.
+- path: http-api.md
+  title: HTTP API
+  description: This guide explains how Laiya's OpenAI-compatible HTTP API handles
+    routing, proxying, and streaming.
+- path: chatgpt-codex.md
+  title: ChatGPT Codex Provider
+  description: This guide explains how to run the experimental Codex provider with
+    a ChatGPT login while keeping tool execution on the client.

data/context/providers-and-models.md

@@ -0,0 +1,104 @@
+# Providers and Models
+
+This guide explains how to route model IDs to providers and when to discover a provider's model catalog.
+
+## Default Provider
+
+Use a default provider when one upstream should receive any model name:
+
+```ruby
+configuration = Laiya::Configuration.build do |builder|
+	builder.provider :ollama, Laiya::Provider::Ollama.new
+	builder.default_provider :ollama
+end
+```
+
+With no explicit model routes or discovery setting, Laiya forwards
+`GET /v1/models` to the default provider and passes completion requests through
+to it.
+
+## Discover Models from an Upstream
+
+Providers such as Ollama expose an OpenAI-compatible `GET /v1/models` endpoint.
+Use `models: :discover` to query it at runtime instead of copying model names
+into configuration:
+
+```ruby
+configuration = Laiya::Configuration.build do |builder|
+	builder.provider :ollama, Laiya::Provider::Ollama.new, models: :discover
+	builder.default_provider :ollama
+end
+```
+
+`Laiya::Models::Discover` fetches and caches the provider's catalog for 60
+seconds. Laiya uses the discovered IDs for `GET /v1/models` and routes requests
+for those IDs to the provider. The builder itself does not make network calls.
+
+For multiple providers, enable discovery on each provider. Distinct model IDs
+are routed automatically. If two providers advertise the same ID, the default
+provider wins; an explicit `builder.model` route overrides discovery:
+
+```ruby
+configuration = Laiya::Configuration.build do |builder|
+	builder.provider :openai, Laiya::Provider::OpenAI.new(
+		api_key: ENV.fetch("OPENAI_API_KEY")
+	), models: :discover
+	builder.provider :ollama, Laiya::Provider::Ollama.new, models: :discover
+	
+	builder.model "llama3.2", provider: :ollama
+	builder.default_provider :openai
+end
+```
+
+## Expose Model Limits
+
+OpenAI's standard model-list format has no context-window fields. Laiya lets
+you attach a display name and limits to an explicit model route; it publishes
+them under its `laiya` extension field:
+
+```ruby
+configuration = Laiya::Configuration.build do |builder|
+	builder.provider :ollama, Laiya::Provider::Ollama.new, models: :discover
+	builder.model "llama3.2",
+		provider: :ollama,
+		display_name: "Llama 3.2",
+		limits: {context: 32_768, input: 28_672, output: 4_096}
+	builder.default_provider :ollama
+end
+```
+
+The `limits` keys are `context`, `input`, and `output`, and values are positive
+token counts. OpenCode does not currently infer these custom fields from
+`GET /v1/models`; configure its model `limit.context`, `limit.input`, and
+`limit.output` values on each client as well. The `context` limit should match
+the effective upstream model configuration (for Ollama, including `num_ctx`).
+
+## Customize Discovery
+
+Subclass `Laiya::Models::Discover` to filter models or attach provider-specific
+metadata. Override `include_model?` to filter entries and `normalize_model` to
+add or adjust model fields:
+
+```ruby
+class LocalModels < Laiya::Models::Discover
+	protected
+	
+	def include_model?(model)
+		super && model["id"].start_with?("llama")
+	end
+	
+	def normalize_model(model)
+		super.merge("laiya" => {"limits" => {"context" => 32_768, "output" => 4_096}})
+	end
+end
+
+ollama = Laiya::Provider::Ollama.new
+configuration = Laiya::Configuration.build do |builder|
+	builder.provider :ollama, ollama, models: LocalModels.new(ollama)
+	builder.default_provider :ollama
+end
+```
+
+The model list includes configured IDs and discovered metadata. Custom discovery
+metadata is provider-specific and is likewise exposed under Laiya's extension
+field; standard clients may ignore it.

data/examples/chatgpt/authentication.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "json"
+require "openssl"
+require "protocol/http/middleware"
+
+module Examples
+	module ChatGPT
+		# Requires a local API key before forwarding to the personal Codex account.
+		class Authentication < Protocol::HTTP::Middleware
+			def initialize(delegate, token:)
+				super(delegate)
+				raise ArgumentError, "LAIYA_API_KEY must not be empty" if token.empty?
+				
+				@token = token
+			end
+			
+			def call(request)
+				scheme, supplied = request.headers["authorization"].to_s.split(" ", 2)
+				
+				unless valid_token?(scheme, supplied)
+					return Protocol::HTTP::Response[
+						401,
+						{"content-type" => "application/json", "www-authenticate" => "Bearer"},
+						[JSON.dump(error: {message: "Invalid API key", type: "authentication_error"})],
+					]
+				end
+				
+				return @delegate.call(request)
+			end
+			
+			private
+			
+			def valid_token?(scheme, supplied)
+				return false unless scheme == "Bearer" && supplied
+				return false unless supplied.bytesize == @token.bytesize
+				
+				OpenSSL.fixed_length_secure_compare(supplied, @token)
+			end
+		end
+	end
+end

data/examples/chatgpt/readme.md

@@ -0,0 +1,107 @@
+# Laiya with ChatGPT Codex
+
+This example uses `Laiya::Provider::Codex` to adapt Laiya's OpenAI Chat
+Completions API to OpenAI's Codex Responses backend. It loads the ChatGPT login
+from the Codex CLI's file-based credentials, refreshes credentials as needed,
+and converts Responses events—including function calls—back to Chat Completions.
+Tools are returned to the API caller; Laiya does not execute them.
+
+This is an experimental, single-account integration with the Codex-specific
+backend, not the public OpenAI Platform API. Backend behavior and supported
+models may change. OpenAI documents ChatGPT authentication for local Codex
+workflows and trusted private automation; do not run this as a public or
+multi-user service.
+
+## Prepare credentials
+
+The Codex provider reads `CODEX_HOME/auth.json` (default `~/.codex/auth.json`).
+It requires ChatGPT login credentials with access and refresh tokens. If the
+Codex CLI currently stores credentials in the OS keyring, configure file-based
+storage in `~/.codex/config.toml`:
+
+```toml
+cli_auth_credentials_store = "file"
+```
+
+Then run `codex login` and verify `codex login status`. Laiya never prints or
+logs the credential values. Treat `auth.json` as a password; on a remote host,
+transfer it only through a secret manager or another trusted secure channel and
+restrict its permissions to the service account.
+
+## Run locally
+
+Create a client key and start the service from the Laiya repository root:
+
+```sh
+export LAIYA_API_KEY="$(openssl rand -hex 32)"
+bundle install
+bundle exec ruby examples/chatgpt/service.rb
+```
+
+By default it binds only to `127.0.0.1:9293`. Keep it local unless you put it
+behind TLS and an access-controlled gateway. The service requires the caller to
+send the `LAIYA_API_KEY` as a Bearer token; this is separate from the Codex
+credentials used upstream.
+
+`LAIYA_CHATGPT_MODEL` selects the model exposed by `GET /v1/models` and sent to
+the Codex backend. It defaults to `gpt-6-luna`; set it to a model available to
+your account. Set `CODEX_HOME` if the credential file is in a non-default
+directory. `LAIYA_URL` can change the bind endpoint; do not bind publicly
+without TLS and network access controls.
+
+## Try it
+
+```sh
+curl http://127.0.0.1:9293/v1/chat/completions \
+  -H "authorization: Bearer $LAIYA_API_KEY" \
+  -H 'content-type: application/json' \
+  -d '{"model":"gpt-6-luna","messages":[{"role":"user","content":"Say hello"}]}'
+```
+
+For the native Responses endpoint, send `input` as message items (this is also
+the format used when preserving tool-call history):
+
+```sh
+curl -sS http://127.0.0.1:9293/v1/responses \
+  -H "authorization: Bearer $LAIYA_API_KEY" \
+  -H 'content-type: application/json' \
+  -d '{"model":"gpt-6-luna","input":[{"role":"user","content":[{"type":"input_text","text":"Reply with exactly: Laiya connected"}]}]}'
+```
+
+Use `/v1/responses` for Codex tool calling. Laiya preserves the Responses API
+tool-call items and streaming events, so the client executes the tools and
+sends `function_call_output` items in the next request. The text-only
+`/v1/chat/completions` adapter rejects tool-enabled requests because converting
+away Codex's encrypted reasoning state would break some tool continuations.
+Send full Responses input history on each request; `previous_response_id` is not
+available because the Codex backend is used statelessly.
+
+## Connect OpenCode from another computer
+
+Put the service behind TLS and an access-controlled network gateway, then add a
+custom Responses-capable OpenAI provider to OpenCode. Keep the Laiya API key in
+the client machine's secret configuration rather than committing it:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "laiya": {
+      "npm": "@ai-sdk/openai",
+      "name": "Laiya Codex",
+      "options": {
+        "baseURL": "https://laiya.example.com/v1",
+        "apiKey": "<LAIYA_API_KEY>"
+      },
+      "models": {
+        "gpt-6-luna": {"name": "GPT-6 Luna"}
+      }
+    }
+  },
+  "model": "laiya/gpt-6-luna"
+}
+```
+
+OpenCode uses `/v1/responses` for this provider. The model can return tool calls,
+which OpenCode executes on the client computer and reports back on subsequent
+requests; Laiya never executes client tools.

data/examples/chatgpt/service.rb

@@ -0,0 +1,34 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "async/http"
+require "async/service"
+require "async/service/managed/environment"
+require "laiya"
+require "laiya/environment/application"
+require_relative "authentication"
+
+configuration = Async::Service::Configuration.build do
+	service "laiya-chatgpt" do
+		include Laiya::Environment::Application
+		
+		configuration do
+			Laiya::Configuration.build do |builder|
+				builder.provider :codex, Laiya::Provider::Codex.new
+				builder.model ENV.fetch("LAIYA_CHATGPT_MODEL", "gpt-6-luna"), provider: :codex
+				builder.default_provider :codex
+			end
+		end
+		
+		application do
+			Examples::ChatGPT::Authentication.new(super(),
+				token: ENV.fetch("LAIYA_API_KEY"),
+			)
+		end
+	end
+end
+
+Async::Service::Controller.run(configuration)

data/guides/chatgpt-codex/readme.md

@@ -0,0 +1,43 @@
+# ChatGPT Codex Provider
+
+This guide explains how to run the experimental Codex provider with a ChatGPT login while keeping tool execution on the client.
+
+## Authentication and Trust
+
+The Codex provider reads ChatGPT credentials from
+`CODEX_HOME/auth.json` (default `~/.codex/auth.json`) and refreshes tokens when
+needed. If the Codex CLI uses an OS keyring, configure file-backed credentials
+and run `codex login`:
+
+```toml
+cli_auth_credentials_store = "file"
+```
+
+Treat `auth.json` as a password. This provider calls the Codex-specific backend,
+not the public OpenAI Platform API. It is experimental and intended for a
+trusted, single-user service. Do not expose it to the public internet or an
+untrusted multi-user environment.
+
+## Start the Example
+
+From the Laiya repository root:
+
+```sh
+export LAIYA_API_KEY="$(openssl rand -hex 32)"
+bundle exec ruby examples/chatgpt/service.rb
+```
+
+The example binds to `127.0.0.1:9293`. It requires the client to send the
+separate `LAIYA_API_KEY` as a Bearer token. For remote clients, use TLS and a
+private access-controlled network. See the [example files](https://github.com/socketry/laiya/tree/main/examples/chatgpt).
+
+## Client-Owned Tool Execution
+
+Use `POST /v1/responses` for tool calling. Laiya preserves the Codex Responses
+stream and response items. The client executes a returned function call and
+sends its `function_call_output` back in the next request. Since Codex is used
+statelessly, send the full input history, including the previous response's
+reasoning and function-call items; `previous_response_id` is not supported.
+
+The text-only `POST /v1/chat/completions` adapter rejects tool-enabled requests
+so it cannot silently lose Codex reasoning state.

data/guides/getting-started/readme.md

@@ -0,0 +1,49 @@
+# Getting Started
+
+This guide explains how to install Laiya, configure a provider, and make an OpenAI-compatible request.
+
+## Installation
+
+Add Laiya to your application:
+
+```sh
+bundle add laiya
+```
+
+## Configure a Provider
+
+Laiya's Ruby API uses a `Laiya::Configuration` to connect model IDs to
+providers. For an OpenAI Platform API key:
+
+```ruby
+require "laiya"
+
+configuration = Laiya::Configuration.build do |builder|
+	builder.provider :openai, Laiya::Provider::OpenAI.new(
+		api_key: ENV.fetch("OPENAI_API_KEY")
+	)
+	builder.model "gpt-4.1-mini", provider: :openai
+	builder.default_provider :openai
+end
+
+application = Laiya::Web::Application.new(configuration: configuration)
+```
+
+The provider forwards `Protocol::HTTP::Request` and `Protocol::HTTP::Response`
+objects using `Async::HTTP`. It does not parse OpenAI request or response bodies
+in the direct proxy path.
+
+For Ollama and multi-provider setups, see [Providers and Models](../providers-and-models/).
+
+## Run the API Service
+
+For a local OpenAI API proxy, set the API key and start Laiya:
+
+```sh
+export OPENAI_API_KEY="..."
+bundle exec bin/laiya
+```
+
+The service listens on `http://localhost:9292` by default. Configure `LAIYA_URL`
+to change the endpoint. See [HTTP API](../http-api/) for supported routes and
+streaming behavior.

data/guides/http-api/readme.md

@@ -0,0 +1,49 @@
+# HTTP API
+
+This guide explains how Laiya's OpenAI-compatible HTTP API handles routing, proxying, and streaming.
+
+## Run the Async Service
+
+Laiya runs directly on `Async::HTTP::Server` under `Async::Service`; it does not
+use Rack:
+
+```sh
+bundle exec bin/laiya
+```
+
+The default service listens on `http://localhost:9292`. `LAIYA_URL` configures
+the endpoint. `bin/laiya` loads optional Ruby configuration paths supplied on
+the command line before starting the service.
+
+## Endpoints
+
+The API accepts OpenAI-compatible `Protocol::HTTP::Request` objects and returns
+`Protocol::HTTP::Response` objects. Supported common routes include:
+
+- `GET /v1/models`
+- `POST /v1/chat/completions`
+- `POST /v1/responses` when the configured provider supports it
+- Other OpenAI-compatible paths are forwarded to the selected provider.
+
+Configured model routes produce a Laiya model catalog. When a provider is the
+default and no model catalog is configured, `GET /v1/models` is forwarded
+upstream. See [Providers and Models](../providers-and-models/) for discovery.
+
+## Proxy and Model Routing
+
+The built-in OpenAI provider is a direct HTTP proxy. It forwards the method,
+path, headers, and request body, replacing authorization with its configured
+upstream key and filtering hop-by-hop headers. It returns the upstream response
+without parsing its body.
+
+When a model route or discovery source is configured, Laiya buffers and rewinds
+request bodies for known JSON completion endpoints to read the `model` field.
+It forwards the original body unchanged. Streaming response bodies are not
+buffered by the router.
+
+## Streaming
+
+OpenAI-compatible upstream SSE responses pass through unchanged. Translating
+providers may adapt streaming formats. The Codex Responses endpoint passes
+native Responses SSE through, including tool-call events; Laiya does not execute
+client tools.

data/guides/index.md

@@ -0,0 +1,14 @@
+# Guides
+
+Use these guides to set up Laiya, route OpenAI-compatible requests to providers,
+and run the HTTP API.
+
+## Getting Started
+
+- [Getting Started](getting-started/) — Install Laiya and make your first request.
+
+## Configuration
+
+- [Providers and Models](providers-and-models/) — Configure provider routes and discover upstream models.
+- [HTTP API](http-api/) — Run the async service and understand proxy and streaming behavior.
+- [ChatGPT Codex](chatgpt-codex/) — Use the experimental Codex provider with ChatGPT login credentials.

data/guides/links.yaml

@@ -0,0 +1,8 @@
+getting-started:
+  order: 1
+providers-and-models:
+  order: 2
+http-api:
+  order: 3
+chatgpt-codex:
+  order: 4