polyglot-adapter

polyglot-adapter provides runtime and build-time support for executing Python and JavaScript on the JVM through GraalVM Polyglot.

It provides:

• runtime execution APIs for embedded polyglot calls
• Spring Boot integration for declarative client binding
• build-time code generation from contracts

Runtime Positioning

• Python is the primary and more mature runtime path.
• JavaScript support is intentionally narrower and currently treated as experimental.
• Public contract guidance lives in README.md, docs/public-api.md, docs/stability.md, docs/compatibility.md, and docs/runtime-semantics.md.
• Startup preload is raw script evaluation; it does not prebind contracts or hydrate interface caches.
• Shared starter executors serialize access to one GraalVM context (safe-by-serialization, not throughput-oriented parallel execution).

Table of Contents

• Requirements
• Repository Layout
• Modules
• Installation
• Runtime Quick Start
• Build
• Development
• Documentation
• Samples
• OSS Project Policies
• License

Requirements

• Repository minimum Java: JDK 21+, Maven 3.9+
• Verified runtime line: GraalVM JDK 25.x, Maven 3.9+
• CI and local quality checks assume the Maven wrapper: ./mvnw

Current verified repository line:

• repository modules compile against Java 21
• repository CI explicitly exercises Java 21 as the minimum baseline
• runtime modules and maintained sample verification currently run on Java 25 / GraalVM 25.x
• the repository currently verifies a Spring Boot 4.0.4 starter and maintained sample line

Current contract boundaries:

• Python-first runtime binding and starter usage are the primary stabilization path toward 1.0.0
• JavaScript remains part of the published API surface, but only as an explicitly experimental path
• internal starter types and runtime implementation classes are not supported extension points

When working from this repository, load the pinned SDKMAN environment first:

sdk env

Repository Layout

The repository is organized into three layers:

• api: shared annotations and contract model
• runtime: core executor API, Spring Boot integration, and BOM
• build-tools: contract parsing and Java interface generation

Modules

• api/polyglot-annotations: public annotations such as @PolyglotClient
• api/polyglot-model: contract model, parser SPI, and configuration abstractions
• runtime/polyglot-adapter: framework-neutral GraalVM execution layer
• runtime/polyglot-spring-boot-starter: Spring Boot auto-configuration, client binding, health, and metrics
• runtime/polyglot-bom: dependency management for runtime consumers
• build-tools/polyglot-codegen: contract parser and Java source generator
• build-tools/polyglot-codegen-maven-plugin: Maven integration for code generation

Installation

Artifacts are published under:

• Group ID: io.github.ih0r-d
• BOM: polyglot-bom
• Core runtime: polyglot-adapter
• Spring Boot starter: polyglot-spring-boot-starter

Import the runtime BOM:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>io.github.ih0r-d</groupId>
      <artifactId>polyglot-bom</artifactId>
      <version>${polyglot.version}</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Use the latest published version for ${polyglot.version}. The current development line on main is 0.3.1-SNAPSHOT.

Add the core adapter:

<dependency>
  <groupId>io.github.ih0r-d</groupId>
  <artifactId>polyglot-adapter</artifactId>
</dependency>

Add the Spring Boot starter if needed:

<dependency>
  <groupId>io.github.ih0r-d</groupId>
  <artifactId>polyglot-spring-boot-starter</artifactId>
</dependency>

Runtime Quick Start

This quick start follows the repository's primary Python-first path. JavaScript support remains experimental and is documented separately in docs/runtime.md.

Typical Spring Boot happy path:

@SpringBootApplication
@EnablePolyglotClients
class DemoApplication {}

@PolyglotClient
public interface GreetingService {
  String hello(String name);
}

Minimal Spring Boot configuration:

polyglot:
  core:
    fail-fast: true
  python:
    enabled: true
    resources-path: classpath:python
    warmup-on-startup: true

When @EnablePolyglotClients does not declare basePackages, the starter scans the package of the importing configuration class.

Add only the language runtimes you enable:

<dependency>
  <groupId>org.graalvm.python</groupId>
  <artifactId>python-embedding</artifactId>
</dependency>
<dependency>
  <groupId>org.graalvm.python</groupId>
  <artifactId>python-launcher</artifactId>
</dependency>
<dependency>
  <groupId>org.graalvm.js</groupId>
  <artifactId>js</artifactId>
  <type>pom</type>
</dependency>

Build

Run the full build:

./mvnw clean verify

Run the stricter local quality gate:

./mvnw -B -ntp -Pquality verify

Development

Local developer tooling and helper scripts are available in .dev/.

If present, start with .dev/README.md for local workflows, helper commands, and repository-specific development utilities.

Main project commands use the Maven wrapper:

sdk env
./mvnw clean verify
./mvnw -B -ntp -Pquality verify

Release preparation flow:

task -t .dev/Taskfile.yaml release-preflight
task -t .dev/Taskfile.yaml release -- <version>

release-preflight is the required local gate before release. It verifies the quality profile, strict docs build, local artifact installation, and maintained samples.

Documentation

Project documentation is maintained in docs/. Start with docs/index.md.

• docs/index.md
• docs/overview.md
• docs/architecture.md
• docs/compatibility.md
• docs/public-api.md
• docs/stability.md
• docs/runtime.md
• docs/runtime-semantics.md
• docs/codegen.md
• docs/concepts.md
• docs/release-checklist.md
• docs/release-gates.md
• docs/release-process.md
• docs/roadmap.md

Samples

The samples/ directory contains maintained example applications aligned with the current development line on main. On this branch they target 0.3.1-SNAPSHOT, so run a local ./mvnw -DskipTests install first when building them from source.

• samples/java-maven-example: framework-neutral runtime API with FileSystemScriptSource
• samples/java-maven-codegen-example: code generation plus runtime binding
• samples/spring-boot-example: Spring Boot starter, @PolyglotClient, actuator, and metrics
• samples/java-python-aot-adapter: fat JAR and native-image packaging for a Python-backed contract
• samples/polyglot-ai-demo: multi-contract Python runtime pipeline using handwritten Java interfaces

Canonical behavior and supported configuration are documented in docs/.

OSS Project Policies

• Contribution guide: CONTRIBUTING.md
• Security policy: SECURITY.md
• Changelog: CHANGELOG.md
• Code of conduct: CODE_OF_CONDUCT.md

License

Licensed under the Apache License 2.0.