AI API

Provider-native LLM calls for Openplanet plugins.

tm-aiapi is a small shared Openplanet library plugin for calling Anthropic-compatible Messages APIs and OpenAI Chat Completions/Responses from AngelScript. It normalizes text, tool calls, usage, and provider errors while retaining provider-native state when a multi-turn tool loop requires it.

Platform	Trackmania (current) + Openplanet
Endpoints	Anthropic-compatible Messages; OpenAI Chat Completions and Responses
Consumers	Openplanet AngelScript plugins such as tm-agent
License	Dual Unlicense or CC0 1.0 — public domain / no attribution required
Status	Active development (info.toml 0.1.0)
Releasing	RELEASE.md · CHANGELOG.md

Capabilities

• Shared provider interface — consumers depend on ILlmProvider, not request internals.
• Provider routing — OpenAI model prefixes can select /v1/responses; other models use Chat Completions.
• Tool schema conversion — accepts the agent's Anthropic-style name / description / input_schema definitions and emits endpoint-native schemas.
• Normalized responses — text, function calls, call IDs, token usage, errors, and raw provider data use a stable result shape.
• Reasoning continuity — encrypted OpenAI Responses reasoning items are requested, parsed, returned, stored by the consumer, and replayed across stateless tool turns.
• Defensive networking — malformed, null, and non-object success responses are normalized instead of crashing consumer coroutines.

Install for development

git clone https://github.com/clankercode/tm-aiapi.git
cd tm-aiapi
./build.sh dev

This stages src/ and info.toml under ~/OpenplanetNext/Plugins/ai-api, runs Openplanet LSP when available, and reloads through tm-remote-build when available.

A consumer declares the dependency in info.toml:

[script]
dependencies = ["ai-api"]

Exported API

The plugin exports:

• AiApi::Anthropic_Complete(...)
• AiApi::OpenAI_Complete(...)
• AiApi::NewOpenAIProvider(...)
• shared interfaces and helpers from AiApi_Interfaces.as, AiApi_Helpers.as, and AiApi_TokenCount.as

The class-based OpenAI provider is the preferred integration for consumers that need endpoint routing and normalized provider results.

Response model

Provider calls return a JSON object with this normalized shape (some providers omit reasoning_items; usage is null when the endpoint did not report it):

{
  "text": null,
  "tool_calls": [],
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 0
  },
  "reasoning_items": []
}

On failure, error contains a human-readable provider or network error; the other normalized fields retain their empty/null defaults. Consumers should still treat provider calls as fallible and restore their own UI/run state if an imported call throws.

Development and release

./build.sh dev            # stage DEV build and reload
./build.sh unittest       # run compile-time Responses failure fixtures
./build.sh release-check  # stage release-like build without DEV
./build.sh release        # build ai-api-<version>.op

openplanet-lsp check --plugins-dir "$HOME/OpenplanetNext/Plugins" \
  --plugins-dir .. --plugin-files-search-path src .

See RELEASE.md. The unittest mode loads compile-time fixtures that verify Responses failure normalization. When ai-api changes for tm-agent, validate and release the dependency first, then run the dependent plugin's release-like compile, tests, and package gate against it.

The HTML source for the README diagram is committed at docs/assets/readme-hero.html. Regenerate the committed 1600×900 RGB PNG with Playwright Chromium at device-pixel ratio 1, after fonts are ready:

node docs/assets/render-readme-hero.mjs

The renderer uses only system/UI fallback fonts declared in the HTML; install its local playwright dependency and Chromium once with npm install then npx playwright install chromium when bootstrapping a new machine.

Security

API keys are provided by the consuming plugin and sent only to the selected provider endpoint. Do not log keys, commit them, or include them in screenshots. Review any new provider URL before use.

License

Use this project under either The Unlicense or CC0 1.0 Universal, at your option. No attribution is required. See LICENSE for the short dual-license notice.