orizu 0.3.1 → 0.3.3

package/src/index.ts

@@ -99,6 +99,62 @@ interface PromptSummary {
   description?: string | null
 }
 
+interface PromptCommentAuthor {
+  name: string
+  initials?: string
+  color?: string
+}
+
+interface PromptCommentAnchor {
+  text: string | null
+  startLine: number | null
+  endLine: number | null
+}
+
+interface PromptCommentReply {
+  id: string
+  body: string
+  author: PromptCommentAuthor
+  createdAt: string
+  updatedAt: string
+}
+
+interface PromptCommentThread {
+  id: string
+  status: 'open' | 'resolved'
+  body: string
+  anchor: PromptCommentAnchor | null
+  author: PromptCommentAuthor
+  createdAt: string
+  updatedAt: string
+  resolvedAt: string | null
+  resolvedByUserId: string | null
+  replyCount: number
+  replies: PromptCommentReply[]
+}
+
+interface PromptCommentsPayload {
+  prompt: {
+    id: string
+    name: string
+    role: string
+    description?: string | null
+  }
+  version: {
+    id: string
+    versionNumber?: number
+    versionLabel?: string | null
+    status?: string | null
+  }
+  summary: {
+    threadCount: number
+    openThreadCount: number
+    resolvedThreadCount: number
+    replyCount: number
+  }
+  comments: PromptCommentThread[]
+}
+
 interface ScorerSummary {
   id: string
   name: string
@@ -200,11 +256,11 @@ function printVersion() {
 }
 
 function printUsage() {
-  printLine(`orizu global options:\n\n  --local                 Use http://localhost:3000\n  --server <url>          Use a specific server origin (for example: https://preview.example.com)\n  --version, -v           Print the orizu CLI version\n\norizu commands:\n\n  orizu login [--no-prompt-if-logged-in]\n  orizu logout\n  orizu whoami\n  orizu env [--project <team/project>] [--project-id <projectId>]\n  orizu log <event_type> --run-id <id> --sequence <n> --payload @event.json\n  orizu teams list\n  orizu teams create [--name <name>]\n  orizu teams members list [--team <teamSlug>]\n  orizu teams members add --email <email> [--team <teamSlug>]\n  orizu teams members remove --email <email> [--team <teamSlug>]\n  orizu teams members role --team <teamSlug> --email <email> --role <admin|member>\n  orizu projects list [--team <teamSlug>]\n  orizu projects create --name <name> [--team <teamSlug>]\n  orizu prompts list --project <team/project>\n  orizu prompts pull <prompt-id-or-name> --project <team/project> --out <dir> [--label <label> | --version <id>] [--json]\n  orizu prompts push <dir> [--runner-version <id>] [--project <team/project>] [--parent <version-id>] [--json]\n  orizu prompts labels set <prompt-name> <label> --version <version-id> [--project <team/project>] [--json]\n  orizu prompts scorers set-headline <prompt-id> --scorer-version <id> [--dataset-version <id> --split-set <id> --split <name>] [--project <team/project>] [--json]\n  orizu prompts scorers add <prompt-id> --scorer-version <id> [--dataset-version <id> --split-set <id> --split <name>] [--project <team/project>] [--json]\n  orizu scorers list --project <team/project>\n  orizu scorers register --project <team/project> --name <name> --manifest <manifest.json> [--prompt-version <id>] [--runner-version <id>] [--label <label>] [--json]\n  orizu scorers detail <scorer-id-or-name> --project <team/project> [--json]\n  orizu scorers labels set <scorer-name> <label> --version <scorer-version-id> [--project <team/project>] [--json]\n  orizu scores submit <results.jsonl|results.json> --scorer-version <id> --subject-version <prompt-version-id> [--dataset-version <id> --split-set <id> --split <name>] [--project <team/project>] [--json]\n  orizu judges list --project <team/project>\n  orizu judges pull <judge-id-or-name> --project <team/project> --out <dir> [--label <label> | --version <id>] [--json]\n  orizu judges push <dir> [--runner-version <id>] [--project <team/project>] [--parent <version-id>] [--json]\n  orizu runners push <dir> [--project <team/project>] [--name <name>] [--label <label>] [--json]\n  orizu runners exec (--prompt <prompt-version-id> | --prompt-version <id> --runner-version <id> | --scorer-version <id>) --dataset-version <id> --split-set <id-or-name> --split <name> [--runner-dir <dir>] --out <results.jsonl|results.jsonl.gz>\n  orizu optimizers push <dir> [--project <team/project>] [--name <name>] [--label <label>] [--json]\n  orizu runs submit <results.jsonl|results.jsonl.gz> --prompt-version <id> --runner-version <id> --dataset-version <id> --split-set <id> --split <name> [--project <team/project>]\n  orizu apps list [--project <team/project>]\n  orizu apps create --project <team/project> --name <name> --dataset <datasetId> --file <path> --input-schema <json-path> --output-schema <json-path> [--component <name>]\n  orizu apps update [--app <appId>] [--project <team/project>] --file <path> --input-schema <json-path> --output-schema <json-path> [--component <name>]\n  orizu apps link-dataset --dataset <datasetId> [--app <appId>] [--project <team/project>] [--version <n>]\n  orizu apps detail --app <appId> [--project <team/project>] [--json]\n  orizu tasks list [--project <team/project>]\n  orizu tasks create --project <team/project> --dataset <datasetId> --app <appId> --title <title> --assignees <userIdOrEmail1,userIdOrEmail2> [--version <n>] [--instructions <text>] [--labels-per-item <n>] [--json]\n  orizu tasks assign --task <taskId> --assignees <userId1,userId2>\n  orizu tasks status --task <taskId> [--json]\n  orizu tasks pause --task <taskId>\n  orizu tasks unpause --task <taskId>\n  orizu datasets upload --file <path> [--project <team/project>] [--name <name>]\n  orizu datasets push <path> [--project <team/project>] [--name <name>] [--json]\n  orizu datasets versions create <datasetId|dataset-name> [--project <team/project>] [--label <label>] [--json]\n  orizu datasets splits create <datasetVersionId> [--from-file <split.json>] [--json]\n  orizu datasets download [--dataset <datasetId|datasetUrl>] [--project <team/project>] [--format <csv|json|jsonl>] [--out <path>]\n  orizu datasets append [--dataset <datasetId|datasetUrl>] [--project <team/project>] --file <path>\n  orizu datasets edit-rows [--dataset <datasetId|datasetUrl>] [--project <team/project>] --file <path>\n  orizu datasets delete-rows [--dataset <datasetId|datasetUrl>] [--project <team/project>] --row-ids <id1,id2>\n  orizu datasets delete [--dataset <datasetId|datasetUrl>] [--project <team/project>]\n  orizu datasets lock [--dataset <datasetId|datasetUrl>] [--project <team/project>] [--reason <text>]\n  orizu datasets clone [--dataset <datasetId|datasetUrl>] [--project <team/project>] [--name <name>]\n  orizu tasks export [--task <taskId>] [--format <csv|json|jsonl>] [--out <path>]`)
+  printLine(`orizu global options:\n\n  --local                 Use http://localhost:3000\n  --server <url>          Use a specific server origin (for example: https://preview.example.com)\n  --version, -v           Print the orizu CLI version\n\norizu commands:\n\n  orizu login [--no-prompt-if-logged-in]\n  orizu logout\n  orizu whoami\n  orizu env [--project <team/project>] [--project-id <projectId>]\n  orizu log <event_type> --run-id <id> --sequence <n> --payload @event.json\n  orizu teams list\n  orizu teams create [--name <name>]\n  orizu teams members list [--team <teamSlug>]\n  orizu teams members add --email <email> [--team <teamSlug>]\n  orizu teams members remove --email <email> [--team <teamSlug>]\n  orizu teams members role --team <teamSlug> --email <email> --role <admin|member>\n  orizu projects list [--team <teamSlug>]\n  orizu projects create --name <name> [--team <teamSlug>]\n  orizu prompts list --project <team/project>\n  orizu prompts comments <prompt-id-or-name> --project <team/project> [--label <label> | --version <id>] [--json]\n  orizu prompts pull <prompt-id-or-name> --project <team/project> --out <dir> [--label <label> | --version <id>] [--json]\n  orizu prompts push <dir> [--runner-version <id>] [--project <team/project>] [--parent <version-id>] [--json]\n  orizu prompts labels set <prompt-name> <label> --version <version-id> [--project <team/project>] [--json]\n  orizu prompts scorers set-headline <prompt-id> --scorer-version <id> [--dataset-version <id> --split-set <id> --split <name>] [--project <team/project>] [--json]\n  orizu prompts scorers add <prompt-id> --scorer-version <id> [--dataset-version <id> --split-set <id> --split <name>] [--project <team/project>] [--json]\n  orizu scorers list --project <team/project>\n  orizu scorers register --project <team/project> --name <name> --manifest <manifest.json> [--prompt-version <id>] [--runner-version <id>] [--label <label>] [--json]\n  orizu scorers detail <scorer-id-or-name> --project <team/project> [--json]\n  orizu scorers labels set <scorer-name> <label> --version <scorer-version-id> [--project <team/project>] [--json]\n  orizu scores submit <results.jsonl|results.json> --scorer-version <id> --subject-version <prompt-version-id> [--dataset-version <id> --split-set <id> --split <name>] [--project <team/project>] [--json]\n  orizu judges list --project <team/project>\n  orizu judges pull <judge-id-or-name> --project <team/project> --out <dir> [--label <label> | --version <id>] [--json]\n  orizu judges push <dir> [--runner-version <id>] [--project <team/project>] [--parent <version-id>] [--json]\n  orizu runners push <dir> [--project <team/project>] [--name <name>] [--label <label>] [--json]\n  orizu runners exec (--prompt <prompt-version-id> | --prompt-version <id> --runner-version <id> | --scorer-version <id>) --dataset-version <id> --split-set <id-or-name> --split <name> [--runner-dir <dir>] --out <results.jsonl|results.jsonl.gz>\n  orizu optimizers push <dir> [--project <team/project>] [--name <name>] [--label <label>] [--json]\n  orizu runs submit <results.jsonl|results.jsonl.gz> --prompt-version <id> --runner-version <id> --dataset-version <id> --split-set <id> --split <name> [--project <team/project>]\n  orizu apps list [--project <team/project>]\n  orizu apps create --project <team/project> --name <name> --dataset <datasetId> --file <path> --input-schema <json-path> --output-schema <json-path> [--component <name>]\n  orizu apps update [--app <appId>] [--project <team/project>] --file <path> --input-schema <json-path> --output-schema <json-path> [--component <name>]\n  orizu apps link-dataset --dataset <datasetId> [--app <appId>] [--project <team/project>] [--version <n>]\n  orizu apps detail --app <appId> [--project <team/project>] [--json]\n  orizu tasks list [--project <team/project>]\n  orizu tasks create --project <team/project> --dataset <datasetId> --app <appId> --title <title> --assignees <userIdOrEmail1,userIdOrEmail2> [--version <n>] [--instructions <text>] [--labels-per-item <n>] [--json]\n  orizu tasks assign --task <taskId> --assignees <userId1,userId2>\n  orizu tasks status --task <taskId> [--json]\n  orizu tasks pause --task <taskId>\n  orizu tasks unpause --task <taskId>\n  orizu datasets upload --file <path> [--project <team/project>] [--name <name>]\n  orizu datasets push <path> [--project <team/project>] [--name <name>] [--json]\n  orizu datasets versions create <datasetId|dataset-name> [--project <team/project>] [--label <label>] [--json]\n  orizu datasets splits create <datasetVersionId> [--from-file <split.json>] [--json]\n  orizu datasets download [--dataset <datasetId|datasetUrl>] [--project <team/project>] [--format <csv|json|jsonl>] [--out <path>]\n  orizu datasets append [--dataset <datasetId|datasetUrl>] [--project <team/project>] --file <path>\n  orizu datasets edit-rows [--dataset <datasetId|datasetUrl>] [--project <team/project>] --file <path>\n  orizu datasets delete-rows [--dataset <datasetId|datasetUrl>] [--project <team/project>] --row-ids <id1,id2>\n  orizu datasets delete [--dataset <datasetId|datasetUrl>] [--project <team/project>]\n  orizu datasets lock [--dataset <datasetId|datasetUrl>] [--project <team/project>] [--reason <text>]\n  orizu datasets clone [--dataset <datasetId|datasetUrl>] [--project <team/project>] [--name <name>]\n  orizu tasks export [--task <taskId>] [--format <csv|json|jsonl>] [--out <path>]`)
 }
 
 function printOptimizationUsage() {
-  printLine(`\nOptimization lifecycle commands:\n\n  orizu optimizations start --project <team/project> --optimizer-version <id> --prompt-version <id[,id]> --selection-scorer <id> [--reflection-scorer <id>] [--pareto-scorer <id>] [--best-scorer <id>] --dataset-version <id> --split-set <id> [--train-split <name>] [--validation-split <name>] [--metadata <json|@file>] [--json]\n  orizu optimizations run-gepa --project <team/project> --optimizer-version-id <id> --candidate-version-id <id> --runner-version-id <id> --candidate-runner-dir <dir> --scorer-version-id <id> --scorer-runner-version-id <id> --scorer-runner-dir <dir> --dataset-version-id <id> --split-set-id <id> [--train-split train] [--val-split validation]\n  orizu optimizations pause <run-id> [--reason <text>] [--json]\n  orizu optimizations resume <run-id> [--json]\n  orizu optimizations finish <run-id> [--best-score <n>] [--best-candidate <id>] [--result-prompt-version <id>] [--metadata <json|@file>] [--json]\n  orizu optimizations fail <run-id> [--reason <text>] [--metadata <json|@file>] [--json]\n  orizu optimizations cancel <run-id> [--reason <text>] [--json]`)
+  printLine(`\nOptimization lifecycle commands:\n\n  orizu optimizations start --project <team/project> --optimizer-version <id> --prompt-version <id[,id]> --selection-scorer <id> [--reflection-scorer <id>] [--pareto-scorer <id>] [--best-scorer <id>] --dataset-version <id> --split-set <id> [--train-split <name>] [--validation-split <name>] [--metadata <json|@file>] [--json]\n  orizu optimizations run-gepa --project <team/project> --optimizer-version-id <id> --candidate-version-id <id> --runner-version-id <id> --candidate-runner-dir <dir> --scorer-version-id <id> --scorer-runner-version-id <id> --scorer-runner-dir <dir> --dataset-version-id <id> --split-set-id <id> [--train-split train] [--val-split validation] [--log-dir logs]\n  orizu optimizations export <run-id> [--out <path>] [--json]\n  orizu optimizations pause <run-id> [--reason <text>] [--json]\n  orizu optimizations resume <run-id> [--json]\n  orizu optimizations finish <run-id> [--best-score <n>] [--best-candidate <id>] [--result-prompt-version <id>] [--metadata <json|@file>] [--json]\n  orizu optimizations fail <run-id> [--reason <text>] [--metadata <json|@file>] [--json]\n  orizu optimizations cancel <run-id> [--reason <text>] [--json]`)
 }
 
 let cliArgs = process.argv.slice(2)
@@ -835,6 +891,78 @@ function printTaskStatusSummary(data: TaskStatusPayload) {
   }
 }
 
+function compactTerminalText(value: string, maxLength = 160): string {
+  const compact = sanitizeTerminalText(value).replace(/\s+/g, ' ').trim()
+  if (compact.length <= maxLength) {
+    return compact
+  }
+
+  return `${compact.slice(0, Math.max(0, maxLength - 1)).trim()}…`
+}
+
+function printIndentedBody(value: string, indent: string) {
+  const lines = sanitizeTerminalText(value || '').split(/\r?\n/)
+  for (const line of lines) {
+    printLine(`${indent}${line}`)
+  }
+}
+
+function formatPromptCommentAnchor(anchor: PromptCommentAnchor | null): string | null {
+  if (!anchor) {
+    return null
+  }
+
+  const lineLabel = anchor.startLine && anchor.endLine
+    ? anchor.startLine === anchor.endLine
+      ? `line ${anchor.startLine}`
+      : `lines ${anchor.startLine}-${anchor.endLine}`
+    : null
+  const selectedText = anchor.text ? `"${compactTerminalText(anchor.text, 180)}"` : null
+
+  if (lineLabel && selectedText) {
+    return `${lineLabel}: ${selectedText}`
+  }
+  return lineLabel || selectedText
+}
+
+function printPromptComments(data: PromptCommentsPayload) {
+  const versionLabel = data.version.versionLabel || (
+    data.version.versionNumber ? `v${data.version.versionNumber}` : data.version.id
+  )
+
+  printLine(`Prompt: ${sanitizeTerminalText(data.prompt.name)} (${sanitizeTerminalText(data.prompt.id)})`)
+  printLine(`Version: ${sanitizeTerminalText(String(versionLabel))} (${sanitizeTerminalText(data.version.id)})`)
+  printLine(
+    `Comments: ${data.summary.threadCount} thread${data.summary.threadCount === 1 ? '' : 's'} ` +
+    `(${data.summary.openThreadCount} open, ${data.summary.resolvedThreadCount} resolved, ${data.summary.replyCount} replies)`
+  )
+
+  if (data.comments.length === 0) {
+    printLine('\nNo comments found for this prompt version.')
+    return
+  }
+
+  for (const [index, thread] of data.comments.entries()) {
+    const authorName = thread.author?.name || 'Unknown'
+    const anchor = formatPromptCommentAnchor(thread.anchor)
+    printLine('')
+    printLine(`${index + 1}. [${thread.status}] ${sanitizeTerminalText(authorName)} · ${sanitizeTerminalText(thread.createdAt)}`)
+    if (anchor) {
+      printLine(`   Selection: ${anchor}`)
+    }
+    printIndentedBody(thread.body, '   ')
+
+    if (thread.replies.length > 0) {
+      printLine(`   Replies (${thread.replies.length})`)
+      for (const reply of thread.replies) {
+        const replyAuthor = reply.author?.name || 'Unknown'
+        printLine(`   - ${sanitizeTerminalText(replyAuthor)} · ${sanitizeTerminalText(reply.createdAt)}`)
+        printIndentedBody(reply.body, '     ')
+      }
+    }
+  }
+}
+
 const DEFAULT_AUTH_CALLBACK_PORT = 43123
 
 function resolveAuthCallbackPort(): number {
@@ -1185,6 +1313,37 @@ async function listJudges() {
   printPromptSummaries(data.judges, 'No judges found.')
 }
 
+async function listPromptComments() {
+  const promptRef = getPositionalArg(2)
+  const project = getArg('--project') || await resolveProjectSlug(null)
+  const label = getArg('--label')
+  const version = getArg('--version')
+
+  if (!promptRef) {
+    throw new Error('Usage: orizu prompts comments <prompt-id-or-name> --project <team/project> [--label <label> | --version <version-id>] [--json]')
+  }
+  if (label && version) {
+    throw new Error('Use either --label or --version, not both')
+  }
+
+  const params = new URLSearchParams({ project })
+  if (label) params.set('label', label)
+  if (version) params.set('version', version)
+
+  const response = await authedFetch(`/api/cli/prompts/${encodeURIComponent(promptRef)}/comments?${params.toString()}`)
+  if (!response.ok) {
+    throw new Error(`Failed to fetch prompt comments: ${await response.text()}`)
+  }
+
+  const data = await parseJsonResponse<PromptCommentsPayload>(response, 'Prompt comments')
+  if (hasJsonFlag()) {
+    printJson(data as unknown as Record<string, unknown>)
+    return
+  }
+
+  printPromptComments(data)
+}
+
 async function listScorers() {
   const project = getArg('--project') || await resolveProjectSlug(null)
   const response = await authedFetch(`/api/cli/scorers?project=${encodeURIComponent(project)}`)
@@ -2070,6 +2229,32 @@ async function updateOptimizationRunLifecycle(action: OptimizationLifecycleActio
   }
 }
 
+async function exportOptimizationRun() {
+  const runId = getPositionalArg(2) || getArg('--run-id')
+  const outPathArg = getArg('--out')
+
+  if (!runId) {
+    throw new Error('Usage: orizu optimizations export <run-id> [--out <path>] [--json]')
+  }
+
+  const response = await authedFetch(`/api/cli/optimization-runs/${encodeURIComponent(runId)}/export`)
+  if (!response.ok) {
+    throw new Error(`Failed to export optimization run: ${await response.text()}`)
+  }
+
+  const data = await parseJsonResponse<Record<string, unknown>>(response, 'Optimization export')
+  if (hasJsonFlag() && !outPathArg) {
+    printJson(data)
+    return
+  }
+
+  const filename = outPathArg
+    ? expandHomePath(outPathArg)
+    : `${runId}.optimization.json`
+  writeTextFileEnsuringDir(filename, `${JSON.stringify(data, null, 2)}\n`)
+  printLine(`Saved optimization export to ${sanitizeTerminalText(filename)}`)
+}
+
 function removeFlagWithValue(args: string[], flag: string): string[] {
   const filtered: string[] = []
   for (let index = 0; index < args.length; index += 1) {
@@ -2083,8 +2268,12 @@ function removeFlagWithValue(args: string[], flag: string): string[] {
 }
 
 function bundledOrizuGepaPythonPath(): string | null {
-  const candidate = fileURLToPath(new URL('../../orizu-gepa-python/src', import.meta.url))
-  return existsSync(candidate) ? candidate : null
+  const candidates = [
+    fileURLToPath(new URL('../vendor/orizu-gepa-python/src', import.meta.url)),
+    fileURLToPath(new URL('../../orizu-gepa-python/src', import.meta.url)),
+  ]
+
+  return candidates.find(candidate => existsSync(candidate)) ?? null
 }
 
 async function runGepaOptimization() {
@@ -3926,6 +4115,11 @@ export async function main(rawArgs = process.argv.slice(2)) {
     return
   }
 
+  if (command === 'prompts' && subcommand === 'comments') {
+    await listPromptComments()
+    return
+  }
+
   if (command === 'prompts' && subcommand === 'pull') {
     await pullPromptArtifact('prompt')
     return
@@ -4021,6 +4215,11 @@ export async function main(rawArgs = process.argv.slice(2)) {
     return
   }
 
+  if (command === 'optimizations' && subcommand === 'export') {
+    await exportOptimizationRun()
+    return
+  }
+
   if (
     command === 'optimizations' &&
     (

package/vendor/orizu-gepa-python/manifest.json

@@ -0,0 +1,9 @@
+{
+  "schema_version": "orizu.optimizer.v1",
+  "name": "orizu-gepa-text",
+  "description": "Orizu-owned text candidate optimizer with GEPA-style reflection and mandatory live event logging.",
+  "language": "python",
+  "command": ["python3", "-m", "orizu_gepa.cli"],
+  "optimizer_family": "gepa",
+  "candidate_kind": "text"
+}

package/vendor/orizu-gepa-python/pyproject.toml

@@ -0,0 +1,16 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "orizu-gepa"
+version = "0.1.0"
+description = "Orizu-owned text prompt optimizer with GEPA-style reflection and mandatory live logging."
+requires-python = ">=3.10"
+dependencies = []
+
+[project.scripts]
+orizu-gepa = "orizu_gepa.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

package/vendor/orizu-gepa-python/src/orizu_gepa/__init__.py

@@ -0,0 +1,19 @@
+from .optimizer import (
+    Budget,
+    DatasetRow,
+    PromptContext,
+    RowEvaluation,
+    TextGepaConfig,
+    TextGepaResult,
+    optimize_text_candidate,
+)
+
+__all__ = [
+    "Budget",
+    "DatasetRow",
+    "PromptContext",
+    "RowEvaluation",
+    "TextGepaConfig",
+    "TextGepaResult",
+    "optimize_text_candidate",
+]

package/vendor/orizu-gepa-python/src/orizu_gepa/cli.py

@@ -0,0 +1,206 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+
+from .client import OrizuClient, OrizuEventSink
+from .local_log import LocalOptimizationLogger
+from .optimizer import TextGepaConfig, optimize_loaded_text_candidate
+from .reflection import reflect_with_provider
+from .runner import make_candidate_runner, make_scorer_runner
+
+
+def positive_int(value: str) -> int:
+    parsed = int(value)
+    if parsed <= 0:
+        raise argparse.ArgumentTypeError("must be positive")
+    return parsed
+
+
+def read_text_arg(value: str | None) -> str | None:
+    if value is None:
+        return None
+    if value.startswith("@"):
+        return Path(value[1:]).read_text()
+    path = Path(value)
+    if path.exists():
+        return path.read_text()
+    return value
+
+
+def read_json_object_arg(value: str | None, flag_name: str) -> dict[str, Any] | None:
+    text = read_text_arg(value)
+    if text is None:
+        return None
+    parsed = json.loads(text)
+    if not isinstance(parsed, dict):
+        raise RuntimeError(f"{flag_name} must be a JSON object")
+    return parsed
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="orizu-gepa")
+    parser.add_argument("--project", required=True)
+    parser.add_argument("--optimizer-version-id", required=True)
+    parser.add_argument("--candidate-version-id", required=True)
+    parser.add_argument("--runner-version-id", required=True)
+    parser.add_argument("--candidate-runner-dir", required=True)
+    parser.add_argument("--scorer-version-id", required=True)
+    parser.add_argument("--scorer-runner-version-id", required=True)
+    parser.add_argument("--scorer-runner-dir", required=True)
+    parser.add_argument("--dataset-version-id", required=True)
+    parser.add_argument("--split-set-id", required=True)
+    parser.add_argument("--train-split", default="train")
+    parser.add_argument("--val-split", default="validation")
+    parser.add_argument("--budget", default="light", choices=["auto", "light", "medium", "high"])
+    parser.add_argument("--max-iterations", type=positive_int, default=3)
+    parser.add_argument("--minibatch-size", type=positive_int, default=3)
+    parser.add_argument(
+        "--candidate-selection-strategy",
+        default=TextGepaConfig.candidate_selection_strategy,
+        choices=["pareto", "current_best", "epsilon_greedy"],
+    )
+    parser.add_argument("--epsilon", type=float, default=TextGepaConfig.epsilon)
+    parser.add_argument("--disable-evaluation-cache", action="store_true")
+    parser.add_argument("--max-metric-calls", type=positive_int)
+    parser.add_argument("--max-full-evals", type=positive_int)
+    parser.add_argument("--reflection-model", default=TextGepaConfig.reflection_model)
+    parser.add_argument("--reflection-temperature", type=float)
+    parser.add_argument("--reflection-prompt-template")
+    parser.add_argument("--reflection-provider-settings")
+    parser.add_argument("--objective", default=TextGepaConfig.objective)
+    parser.add_argument("--seed", type=int, default=0)
+    parser.add_argument("--auto-promote", action="store_true")
+    parser.add_argument("--promotion-label")
+    parser.add_argument("--log-row-snapshots", action="store_true")
+    parser.add_argument("--log-dir", default="logs")
+    parser.add_argument("--no-local-log", action="store_true")
+    parser.add_argument("--metadata", default="{}")
+    args = parser.parse_args()
+
+    metadata = json.loads(args.metadata)
+    if not isinstance(metadata, dict):
+        raise RuntimeError("--metadata must be a JSON object")
+
+    config = TextGepaConfig(
+        budget=args.budget,
+        max_iterations=args.max_iterations,
+        minibatch_size=args.minibatch_size,
+        candidate_selection_strategy=args.candidate_selection_strategy,
+        epsilon=args.epsilon,
+        max_metric_calls=args.max_metric_calls,
+        max_full_evals=args.max_full_evals,
+        reflection_model=args.reflection_model,
+        reflection_temperature=args.reflection_temperature,
+        reflection_prompt_template=read_text_arg(args.reflection_prompt_template),
+        reflection_provider_settings=read_json_object_arg(args.reflection_provider_settings, "--reflection-provider-settings") or {},
+        objective=args.objective,
+        seed=args.seed,
+        auto_promote=args.auto_promote,
+        promotion_label=args.promotion_label,
+        cache_evaluations=not args.disable_evaluation_cache,
+        log_row_snapshots=args.log_row_snapshots,
+    )
+    client = OrizuClient.from_env()
+    prompt_context, trainset = client.fetch_exec_context(
+        prompt_version_id=args.candidate_version_id,
+        runner_version_id=args.runner_version_id,
+        dataset_version_id=args.dataset_version_id,
+        split_set_id=args.split_set_id,
+        split=args.train_split,
+    )
+    _, valset = client.fetch_exec_context(
+        prompt_version_id=args.candidate_version_id,
+        runner_version_id=args.runner_version_id,
+        dataset_version_id=args.dataset_version_id,
+        split_set_id=args.split_set_id,
+        split=args.val_split,
+    )
+    scorer_context, _ = client.fetch_scorer_exec_context(
+        scorer_version_id=args.scorer_version_id,
+        runner_version_id=args.scorer_runner_version_id,
+        dataset_version_id=args.dataset_version_id,
+        split_set_id=args.split_set_id,
+        split=args.val_split,
+    )
+
+    run_metadata = {
+        **metadata,
+        "optimizer_package": "orizu-gepa-python",
+        "optimizer_family": "gepa",
+        "mode": "text-candidate",
+        "inference_lm": prompt_context.provider_settings.get("model"),
+        "reflection_lm": config.reflection_model,
+        "scorer_lm": scorer_context.provider_settings.get("model"),
+        "dataset_size": len(trainset) + len(valset),
+        "train_count": len(trainset),
+        "validation_count": len(valset),
+    }
+
+    run_id = client.start_run(
+        project=args.project,
+        optimizer_version_id=args.optimizer_version_id,
+        prompt_version_id=args.candidate_version_id,
+        scorer_version_id=args.scorer_version_id,
+        dataset_version_id=args.dataset_version_id,
+        split_set_id=args.split_set_id,
+        train_split=args.train_split,
+        validation_split=args.val_split,
+        metadata=run_metadata,
+    )
+    print(f"[orizu-gepa] started optimization run {run_id}", flush=True)
+
+    local_logger = None
+    if not args.no_local_log:
+        local_logger = LocalOptimizationLogger.create(args.log_dir, run_id)
+        local_logger.write_context(
+            project=args.project,
+            run_id=run_id,
+            args={
+                key: value
+                for key, value in vars(args).items()
+                if key not in {"metadata"}
+            },
+            prompt_context=prompt_context,
+            scorer_context=scorer_context,
+            trainset=trainset,
+            valset=valset,
+            metadata=run_metadata,
+        )
+        print(f"[orizu-gepa] local log: {local_logger.path}", flush=True)
+
+    result = optimize_loaded_text_candidate(
+        run_id=run_id,
+        prompt_context=prompt_context,
+        scorer_context=scorer_context,
+        trainset=trainset,
+        valset=valset,
+        candidate_runner=make_candidate_runner(Path(args.candidate_runner_dir), run_id),
+        scorer_runner=make_scorer_runner(Path(args.scorer_runner_dir), run_id),
+        reflector=reflect_with_provider,
+        event_sink=OrizuEventSink(
+            client,
+            run_id,
+            fail_on_log_error=config.fail_on_log_error,
+            local_logger=local_logger,
+        ),
+        config=config,
+        local_logger=local_logger,
+    )
+    if local_logger is not None:
+        local_logger.write_result(result)
+    print(json.dumps({
+        "optimization_run_id": result.run_id,
+        "best_candidate_id": result.best_candidate_id,
+        "best_score": result.best_score,
+        "seed_score": result.seed_score,
+        "promoted_prompt_version_id": result.promoted_prompt_version_id,
+        "budget": result.budget.to_payload(),
+        "local_log_dir": local_logger.path if local_logger is not None else None,
+    }))
+
+
+if __name__ == "__main__":
+    main()