polyglot-adapter is a lightweight Java SDK providing a unified executor-based API for executing and embedding multi-language code (Python, JavaScript) via GraalVM Polyglot. It simplifies context creation, host access management, and interlanguage communication while preserving full control over GraalVM configuration.

✅ Focused on developer experience — predictable, fast, fully composable.

• Unified BaseExecutor API with native Value interop (Value.as(...))
• Automatic host-to-guest binding via Java interfaces (bind())
• Composable Context.Builder API through .apply(...)
• Extensible HostAccess with .extendHostAccess(...)
• Built-in type mappings (Value → Path, user-extendable)
• Virtual File System (VFS) integration for GraalPy
• Fully dependency-free (no frameworks)
• 100% compatible with GraalVM 25.x+

polyglot-adapter/
├── api/
│   ├── context/
│   │   ├── Language.java
│   │   ├── PolyglotContextFactory.java
│   │   └── ResourcesProvider.java
│   └── executors/
│       ├── BaseExecutor.java
│       ├── PyExecutor.java
│       └── JsExecutor.java
├── exceptions/
│   └── EvaluationException.java
└── utils/
    ├── CommonUtils.java
    └── StringCaseConverter.java

• JDK 25+
• Maven 3.9+
• GraalVM 25.x+

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

Add only the runtimes you actually use. Marked as optional to avoid transitive pulls.

<dependency>
  <groupId>org.graalvm.python</groupId>
  <artifactId>python-embedding</artifactId>
  <version>25.0.1</version>
  <optional>true</optional>
</dependency>
<dependency>
  <groupId>org.graalvm.python</groupId>
  <artifactId>python-launcher</artifactId>
  <version>25.0.1</version>
  <optional>true</optional>
</dependency>

<dependency>
  <groupId>org.graalvm.js</groupId>
  <artifactId>js</artifactId>
  <version>25.0.1</version>
  <type>pom</type>
  <optional>true</optional>
</dependency>

try (var executor = PyExecutor.createDefault()) {
    MyApi api = executor.bind(MyApi.class);
    System.out.println(api.add(3, 5)); // 8
}

Python side:

class MyApi:
    def add(self, a, b): return a + b

polyglot.export_value("MyApi", MyApi)

.allowAllAccess(true)
.allowExperimentalOptions(true)

Full access for interop, experimental options for latest GraalPy / GraalJS engines.
These defaults follow Oracle’s embedding best practices for SDKs (not sandboxes).

If sandboxing is needed:

.apply(b -> b.allowAllAccess(false))
.apply(b -> b.allowIO(false))
.hostAccess(HostAccess.NONE);

The SDK adds safe default mappings for convenience:

builder.targetTypeMapping(
    Value.class, Path.class,
    Value::isString, v -> Path.of(v.asString()),
    HostAccess.TargetMappingPrecedence.LOW
);

Users can extend or override mappings freely via:

.extendHostAccess(b -> b.targetTypeMapping(
    Value.class, Instant.class,
    Value::isString, v -> Instant.parse(v.asString())
));

Run all tests (JUnit 5):

mvn clean test

Includes:

• Context creation tests (Python / JS)
• Executor binding and async evaluation tests

Licensed under the Apache License 2.0.
See LICENSE for details.