Interop and Ecosystem Scenarios

Real-world sketches for how the language could work alongside existing AI/ML libraries while remaining AI-native at its core.

These are design scenarios, not finalized syntax. They are meant to answer:

• What user code could look like
• Where interop boundaries live
• Which guarantees remain static vs runtime

If this file and phase-0/ disagree, phase-0/ is authoritative.

Scenario 1: Train in PyTorch, serve with this language runtime

Why this exists

Many teams already train in PyTorch and need a safer, faster, typed serving path.

Workflow

1. Export weights from PyTorch (DLPack / safetensors / custom bridge).
2. Import weights into typed runtime tensors.
3. Compile typed forward pass once.
4. Run inference through runtime dispatch.

What code could look like

// host-side orchestration (pseudo)
let w_q = interop.import_dlpack("torch:q_proj")
let w_k = interop.import_dlpack("torch:k_proj")
let w_v = interop.import_dlpack("torch:v_proj")

// type assertions at boundary
let w_q_typed : Tensor[F16, [D_model, D_model], [D_model mod H = 0]] =
  check_shape_and_refinement w_q

let engine = compile transformer_block_forward
let y = engine.run(x, w_q_typed, w_k, w_v, ...)

What is guaranteed

• Boundary checks enforce dtype/shape/refinement constraints before execution.
• Core execution is explicit typed IR; no hidden broadcast/promotion semantics.

What is not guaranteed

• Bit-identical parity with PyTorch unless explicitly constrained by policy.

Scenario 2: Author custom layer in-language, call from PyTorch

Why this exists

Teams want to write one high-performance custom op/layer and use it from existing Python pipelines.

Workflow

1. Write custom layer in typed language.
2. Compile to shared library/runtime artifact.
3. Expose stable ABI entrypoint.
4. Call from Python extension module.

What code could look like

// language side
public fn rmsnorm_fused [B, S, D](
    x: Tensor[F16, [B, S, D]],
    w: Tensor[F16, [D]],
    eps: Tensor[F16, []]
) -> Tensor[F16, [B, S, D]] =
  ...

# Python side
y = mylang_ops.rmsnorm_fused(x_torch, w_torch, eps_torch)

Key design point

Interop boundary should preserve shape metadata and fail loudly on mismatch, not silently coerce.

Scenario 3: JAX-style transformation pipeline, explicit core semantics

Why this exists

Researchers want JAX-like transform ergonomics (grad/vmap/shard) without opaque tracing semantics.

Workflow

1. Write pure typed function.
2. Apply transformations (eventually effect-handler based in your roadmap).
3. Lower transformed program to target backend.

What code could look like

fn loss_step(params, batch) -> Scalar[F32] =
  cross_entropy(model(params, batch.x), batch.y)

let grad_step = transform.grad(loss_step)
let p_step    = transform.shard(mesh, grad_step)
let compiled  = compile p_step

Benefit

Transform intent is explicit in language constructs, not hidden in host Python meta-programming.

Scenario 4: Dataframe + tensor pipeline (Arrow interop)

Why this exists

Production AI systems mix feature engineering/tabular flows with tensor inference.

Workflow

1. Ingest Arrow table from data system.
2. Type-check schema refinements.
3. Convert selected columns to tensors.
4. Run model.

What code could look like

let df = interop.import_arrow(stream)
let checked : Dataframe[Schema{
  user_id: I64,
  session_len: I32 where session_len >= 1,
  embedding: FixedSizeList[F16, D]
}] = check_schema df

let x : Tensor[F16, [B, D]] = dataframe.to_tensor checked.embedding
let y = model_forward x

Key design point

Dataframe types should be first-class and typed, not encoded as ad hoc tensor conventions.

Scenario 5: Multi-target deployment from one typed source

Why this exists

One model may run on GPU in production, CPU in tests, and a different accelerator later.

Workflow

1. Compile once at typed IR level.
2. Lower to target-specific artifacts by capability profile.
3. Select best available backend at runtime (policy-driven).

What code could look like

let program = compile model_forward

let gpu_artifact = lower program target.cuda_sm90
let cpu_artifact = lower program target.cpu_avx512

let runner = runtime.select([
  prefer(gpu_artifact),
  fallback(cpu_artifact)
])

Key design point

Target capability requirements should be typed/declared, not buried in backend-specific code paths.

Scenario 6: Verification-aware release for safety-critical models

Why this exists

Some users need stronger guarantees than "it usually works".

Workflow

1. Compile program normally for performance.
2. Run translation-validation or proof checks for selected passes.
3. Attach verification metadata to artifact.

What code could look like

let compiled = compile model_forward
let report   = verify.translation_validation compiled

if report.pass then
  publish(compiled, metadata = report)
else
  fail("verification failed")

Key design point

Verification is selective and staged; not every build must pay full proof cost.

Scenario 7: Incremental migration from existing codebases

Why this exists

Real teams rarely rewrite everything at once.

Workflow

• Keep most training loop in PyTorch.
• Migrate hot blocks (attention/FFN/norm) one-by-one.
• Validate numerics and performance per block.

What code could look like

# Existing code mostly unchanged
h = torch_block1(x)
h = mylang_ops.block2(h)      # migrated block
h = torch_block3(h)

Migration policy ideas

• Per-block golden tests vs PyTorch reference.
• Tolerance envelopes by dtype/target.
• ABI snapshots for interop stability.

Cross-scenario primitives and type pressure

These scenarios collectively push for:

1. Current Phase 0 core primitives (good baseline).
2. Phase 1 extensions (variadic-batch matmul, gather, softmax primitive, repeat_interleave).
3. Later first-class non-tensor types (records/sums/effects/dataframe schemas).
4. Stable interop surfaces (DLPack/Arrow/ABI docs).

Practical next docs to add

1. docs/interop/pytorch.md — exact boundary contract and tensor metadata requirements.
2. docs/interop/arrow.md — schema checking and conversion rules.
3. decisions/interop-stability-policy.md — what is stable at each phase.
4. phase-1/ addendum: minimal interop acceptance criteria (one import path, one export path, one roundtrip test).