polyglot-adapter

polyglot-platform provides Java applications with typed access to Python through GraalVM Polyglot, a framework-neutral runtime adapter, a Spring Boot starter, and Maven build tools. JavaScript is available only as an experimental runtime path; JavaScript code generation is unsupported.

It provides:

• runtime execution APIs for embedded polyglot calls
• Java ↔ Python interface binding through PyExecutor and ScriptSource
• Spring Boot auto-configuration for declarative clients, startup validation, optional invocation metrics, and Actuator health/info integration
• Python-to-Java interface generation and opt-in build-time module, symbol, and positional-arity validation, including discovery of explicitly annotated @PolyglotClient interfaces
• opt-in Revapi checks for supported Java APIs and a standalone JMH performance baseline

The optional experimental polyglot-spring-boot-console artifact adds a local, read-only runtime dashboard for Java 25 / Spring Boot 4.1 MVC applications. It is disabled by default and reads existing Micrometer/Actuator services in-process, without exposing Actuator over HTTP. See console setup and security.

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+
• Pinned local runtime and GraalVM/GraalPy Maven artifacts: Oracle GraalVM 25.0.4.1.1
• 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.1.0 starter and maintained sample line

The pinned GraalVM/GraalPy Maven artifacts are 25.0.4.1.1. The recorded JMH results are a single-machine exploratory baseline, not a CI performance gate or a performance guarantee; see benchmarks/README.md and benchmarks/BASELINE.md.

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

Select the exact Oracle JDK using JAVA_HOME or SDKMAN as described in developer tooling. For SDKMAN users:

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 released version for ${polyglot.version} in Maven Central. When building against the current unreleased branch from source, the development line is 0.5.0-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);
}

Place the matching Python module at src/main/resources/python/greeting_service.py:

import polyglot

def hello(name):
    return f"Hello, {name}!"

polyglot.export_value("GreetingService", {"hello": hello})

Enable the Python executor. The starter defaults the resource location to classpath:python, keeps core startup and fail-fast validation enabled, and validates discovered clients during startup:

polyglot:
  python:
    enabled: true

With polyglot.core.fail-fast=true (the default), the starter eagerly creates discovered client beans and resolves their Python bindings during startup. It does not call bound business methods, but loading a Python module and constructing its exported class can run initialization code. Set polyglot.core.fail-fast=false to defer validation for clients that are not otherwise eagerly requested. This runtime check is distinct from the opt-in Maven validate-contracts goal, which statically checks a supported Python source subset without starting GraalVM or executing Python. See runtime semantics, code generation and validation, and troubleshooting.

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

After selecting the JDK through JAVA_HOME or sdk env, run from the repository root:

task dev:setup

task dev:setup enables repository-local Git hooks for this clone, runs a lightweight local validation step, does not publish artifacts, and does not require Maven Central or GPG secrets. Hooks are not enabled automatically after clone.

Common contributor commands:

task verify
task quality
task samples
task format
task docs:serve
task docs:build
task docs:clean

For contribution workflow details, see CONTRIBUTING.md. For the full command reference and developer tooling model, see docs/developer-tooling.md. For API boundaries and supported versions, see Public API, Stability, and Compatibility.

CI Flow

Repository CI runs from .github/workflows/ci.yml on pull requests, pushes to main, and manual dispatch. It is a staged validation pipeline: dependency and vulnerability checks run first, then Java 21 and GraalVM 25 builds, docs and sample validation, quality/security analysis, and finally coverage/SonarCloud reporting.

• Dependency Review runs only for pull requests.
• OSV Scanner runs for pull requests, pushes to main, and manual CI runs.
• OSV scans the Maven CycloneDX aggregate SBOM generated by ./mvnw -B -ntp -Psbom -DskipTests verify; it does not recursively scan the repository in CI.
• CodeQL remains the code security analysis gate.
• Renovate keeps dependency and GitHub Actions updates moving; Snyk is no longer required for CI.
• AOT sample validation is manual-only through workflow_dispatch; it does not appear as skipped jobs on normal pull request or push runs.
• Release is not performed by ci.yml; .github/workflows/release.yaml starts from a release tag push, waits for Checks / Main to pass on the same commit, then deploys docs and creates the GitHub Release.
• Maven Central publishing is not performed by ci.yml; publishing stays manual in .github/workflows/publish.yaml.

The full CI diagram is documented in docs/developer-tooling.md.

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/troubleshooting.md
• docs/developer-tooling.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 0.5.0-SNAPSHOT development line on main. Run a local ./mvnw -DskipTests install first when building them from this repository checkout.

• 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

Optional Polyglot tracing uses Spring-managed Micrometer Tracing and OTLP exporters for individual calls; existing metrics and Console do not require tracing.

License

Licensed under the Apache License 2.0.