Long runs

package com.example.tnsai.docs;

import com.tnsai.idempotency.IdempotencyStore;
import com.tnsai.quality.cost.CostBudgetStore;
import com.tnsai.quality.cost.CostScope;
import com.tnsai.reliability.CheckpointStore;
import com.tnsai.reliability.DefaultResumableRun;
import com.tnsai.reliability.Outcome;
import com.tnsai.reliability.Progress;
import com.tnsai.reliability.ProgressSink;
import com.tnsai.reliability.RunConfig;

import java.math.BigDecimal;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.Optional;
import java.util.function.Consumer;
import java.util.function.UnaryOperator;

public final class LongRunExample {
    private LongRunExample() {}

    // A String state survives the JSON round trip of a Redis or Postgres
    // idempotency store unchanged.
    static final DefaultResumableRun.StateCodec<String> CODEC = new DefaultResumableRun.StateCodec<>() {
        @Override
        public byte[] encode(String state) {
            return state.getBytes(StandardCharsets.UTF_8);
        }

        @Override
        public String decode(byte[] bytes) {
            return new String(bytes, StandardCharsets.UTF_8);
        }
    };

    // Three steps. Only the side-effecting one consults the idempotency store.
    static DefaultResumableRun<String> build(CheckpointStore checkpoints,
                                             IdempotencyStore idempotency,
                                             ProgressSink progress,
                                             UnaryOperator<String> postPr) {
        return DefaultResumableRun.<String>builder()
            .codec(CODEC)
            .checkpointStore(checkpoints)
            .idempotencyStore(idempotency)
            .progressSink(progress)
            .step(DefaultResumableRun.Step.pure("plan", state -> state + "\n[plan]"))
            .step(DefaultResumableRun.Step.sideEffect("post-pr", postPr))
            .step(DefaultResumableRun.Step.pure("verify", state -> state + "\n[verified]"))
            .build();
    }

    static RunConfig config() {
        return RunConfig.builder()
            .maxDuration(Duration.ofHours(8))
            .maxRetries(3)
            .progressTimeout(Duration.ofMinutes(10))
            .build();
    }

    static String summarize(Outcome<String> outcome) {
        return switch (outcome) {
            case Outcome.Completed<String> c -> c.result();
            case Outcome.Failed<String> f -> "failed: " + f.reason();
            case Outcome.Aborted<String> a -> "aborted: " + a.reason();
            case Outcome.Suspended<String> s -> "suspended at " + s.checkpointId();
        };
    }

    // execute() creates the run id. Record it from the first event so that a
    // new process knows which run to resume.
    static final class RunIdRecorder implements ProgressSink {
        private final ProgressSink delegate;
        private final Consumer<String> onNewRun;

        RunIdRecorder(ProgressSink delegate, Consumer<String> onNewRun) {
            this.delegate = delegate;
            this.onNewRun = onNewRun;
        }

        @Override
        public void publish(String runId, Progress event) {
            if (event instanceof Progress.StepStarted started && started.stepIndex() == 0) {
                onNewRun.accept(runId);
            }
            delegate.publish(runId, event);
        }

        @Override
        public Subscription subscribe(String runId, Consumer<Progress> listener) {
            return delegate.subscribe(runId, listener);
        }
    }

    // In a new process: the same steps, the same stores, the saved run id.
    static Outcome<String> resumeAfterCrash(CheckpointStore checkpoints,
                                            IdempotencyStore idempotency,
                                            UnaryOperator<String> postPr,
                                            String runId) {
        return build(checkpoints, idempotency, null, postPr).resume(runId);
    }

    // Abort with BUDGET_EXHAUSTED once the tenant's spend over 24 hours reaches $10.
    static Outcome<String> capped(CheckpointStore checkpoints, CostBudgetStore costs, String tenantId) {
        DefaultResumableRun<String> run = DefaultResumableRun.<String>builder()
            .codec(CODEC)
            .checkpointStore(checkpoints)
            .costMonitor(() -> Optional.of(
                costs.currentSpend(CostScope.tenant(tenantId), Duration.ofHours(24))))
            .step(DefaultResumableRun.Step.pure("draft", state -> state + "\n[draft]"))
            .build();
        return run.execute("start", RunConfig.builder()
            .costCeilingUSD(new BigDecimal("10.00"))
            .build());
    }
}

package com.example.tnsai.docs;

import com.tnsai.annotations.IdempotencyHint;
import com.tnsai.annotations.SideEffect;
import com.tnsai.annotations.Tool;
import com.tnsai.annotations.ToolParam;
import com.tnsai.idempotency.Idempotent;
import com.tnsai.idempotency.KeyStrategy;

import java.util.List;

public final class LongRunToolsExample {
    private LongRunToolsExample() {}

    public static final class GithubTools {

        // REQUIRED: dispatch fails unless @Idempotent gives a stable key and a positive TTL.
        @Tool(name = "github_create_pr",
              description = "Open a pull request on a GitHub repository",
              sideEffect = SideEffect.EXTERNAL,
              idempotencyHint = IdempotencyHint.REQUIRED)
        @Idempotent(strategy = KeyStrategy.HASH_INPUT, ttlSeconds = 86_400)
        public String createPr(@ToolParam(description = "PR title") String title,
                               @ToolParam(description = "Branch to merge") String branch) {
            return "opened '" + title + "' from " + branch;
        }

        // READ: no idempotency hint needed.
        @Tool(name = "github_list_branches",
              description = "List the branches of a GitHub repository",
              sideEffect = SideEffect.READ)
        public List<String> listBranches(@ToolParam(description = "Repository as owner/name") String repo) {
            return List.of("main");
        }
    }
}