PyPI - codex-local-sdk-python - Versions diffs - 0.1.0__py3-none-any.whl - Mend

codex-local-sdk-python 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (46) hide show

codex_sdk_python/data/docs/html documentation/api-reference.html ADDED Viewed

@@ -0,0 +1,218 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>API Reference - SpawnCodex Python SDK Docs</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600;700&display=swap" rel="stylesheet">
+  <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet">
+  <link href="assets/styles.css" rel="stylesheet">
+</head>
+<body>
+  <div class="layout">
+    <aside class="sidebar">
+      <span class="logo">SpawnCodex</span>
+      <h1 class="title">Python SDK Docs</h1>
+      <p class="subtitle">Local Codex non-interactive client</p>
+      <div class="nav-group">
+        <p class="nav-group-label">Overview</p>
+        <a class="nav-link" href="index.html">Home</a>
+        <a class="nav-link" href="getting-started.html">Getting Started</a>
+        <a class="nav-link active" href="api-reference.html">API Reference</a>
+        <a class="nav-link" href="live-threads.html">Live Runs & Threads</a>
+        <a class="nav-link" href="examples.html">Examples Cookbook</a>
+        <a class="nav-link" href="testing-and-quality.html">Testing & Quality</a>
+      </div>
+      <div class="nav-group">
+        <p class="nav-group-label">On This Page</p>
+        <a class="nav-link" href="#exports">Exports</a>
+        <a class="nav-link" href="#core-models">Core Models</a>
+        <a class="nav-link" href="#session-stores">Session Stores</a>
+        <a class="nav-link" href="#core-client">CodexLocalClient</a>
+        <a class="nav-link" href="#telemetry">Telemetry</a>
+        <a class="nav-link" href="#live-run">Live Handles</a>
+        <a class="nav-link" href="#thread-session">Thread Session</a>
+        <a class="nav-link" href="#errors">Errors</a>
+      </div>
+    </aside>
+    <main class="main">
+      <section class="hero">
+        <span class="badge">Reference</span>
+        <h1>Python SDK API Reference</h1>
+        <p>Canonical interface for sync + async execution, retry/timeout control, session metadata persistence, and telemetry hooks.</p>
+      </section>
+      <section class="section" id="exports">
+        <h2>Package Exports</h2>
+        <pre><code>from codex_local_sdk import (
+    AsyncCodexLiveRun,
+    CodexClientEvent,
+    CodexLiveRun,
+    CodexLocalClient,
+    CodexThreadSession,
+    CodexError,
+    CodexExecFailedError,
+    CodexNotInstalledError,
+    CodexEvent,
+    CodexExecRequest,
+    CodexExecResult,
+    RetryPolicy,
+    SandboxMode,
+    SessionStore,
+    InMemorySessionStore,
+    JsonFileSessionStore,
+    SessionRecord,
+    SessionTurnRecord,
+)</code></pre>
+      </section>
+      <section class="section" id="core-models">
+        <h2>Core Models</h2>
+        <h3>CodexExecRequest</h3>
+        <p>Describes <code>codex exec</code> CLI options (prompt, sandbox, model/profile, schema/output flags, images, extra args).</p>
+        <h3>RetryPolicy</h3>
+        <div class="table-wrap">
+          <table>
+            <thead>
+              <tr><th>Field</th><th>Type</th><th>Description</th></tr>
+            </thead>
+            <tbody>
+              <tr><td><code>max_attempts</code></td><td>int</td><td>Total attempts (initial + retries).</td></tr>
+              <tr><td><code>initial_backoff_seconds</code></td><td>float</td><td>Base retry delay.</td></tr>
+              <tr><td><code>backoff_multiplier</code></td><td>float</td><td>Exponential growth factor.</td></tr>
+              <tr><td><code>max_backoff_seconds</code></td><td>float</td><td>Delay cap.</td></tr>
+              <tr><td><code>retry_on_exit_codes</code></td><td>tuple[int, ...] | None</td><td><code>None</code> retries any non-zero exit code.</td></tr>
+              <tr><td><code>jitter_ratio</code></td><td>float</td><td>Random jitter fraction applied to backoff delay.</td></tr>
+              <tr><td><code>max_total_retry_seconds</code></td><td>float | None</td><td>Caps total time spent retrying.</td></tr>
+              <tr><td><code>retry_on_timeouts</code></td><td>bool</td><td>Controls retry behavior for timeout failures.</td></tr>
+            </tbody>
+          </table>
+        </div>
+        <h3>CodexExecResult</h3>
+        <p>Command result with return code, stdout/stderr, final message, events, thread id, turn status, usage, and duration.</p>
+      </section>
+      <section class="section" id="session-stores">
+        <h2>Session Stores</h2>
+        <p>Session stores map logical names to Codex session IDs and persist metadata/history records.</p>
+        <h3>SessionStore Interface</h3>
+        <ul>
+          <li><code>get(name)</code>, <code>set(name, session_id)</code>, <code>delete(name)</code>, <code>all()</code></li>
+          <li><code>get_record(name)</code>, <code>set_record(name, record)</code>, <code>list_records()</code></li>
+        </ul>
+        <h3>SessionRecord / SessionTurnRecord</h3>
+        <ul>
+          <li><code>SessionRecord</code>: session id/name, counters, timestamps, and bounded turn history.</li>
+          <li><code>SessionTurnRecord</code>: per-turn metadata (operation, prompt/message preview, return code, status, duration).</li>
+        </ul>
+        <h3>JsonFileSessionStore</h3>
+        <ul>
+          <li>Schema v2 payload with automatic migration from legacy <code>{name: session_id}</code> files.</li>
+          <li>Thread-safe + cross-process safe file locking.</li>
+          <li>Atomic writes via temp file + <code>os.replace</code>.</li>
+        </ul>
+      </section>
+      <section class="section" id="core-client">
+        <h2>CodexLocalClient</h2>
+        <h3>Constructor</h3>
+        <pre><code>CodexLocalClient(
+    codex_bin: str = "codex",
+    default_cwd: str | None = None,
+    default_env: dict[str, str] | None = None,
+    raise_on_error: bool = True,
+    retry_policy: RetryPolicy | None = None,
+    session_store: SessionStore | None = None,
+    event_hook: Callable[[CodexClientEvent], None] | None = None,
+)</code></pre>
+        <h3>Execution Methods</h3>
+        <div class="table-wrap">
+          <table>
+            <thead>
+              <tr><th>Method</th><th>Returns</th><th>Notes</th></tr>
+            </thead>
+            <tbody>
+              <tr><td><code>run(..., timeout_seconds=None)</code></td><td>CodexExecResult</td><td>Sync run with retry policy.</td></tr>
+              <tr><td><code>run_async(..., timeout_seconds=None)</code></td><td>awaitable[CodexExecResult]</td><td>Async wrapper around sync behavior.</td></tr>
+              <tr><td><code>run_prompt(..., api_key=None, timeout_seconds=None)</code></td><td>CodexExecResult</td><td>Prompt convenience wrapper.</td></tr>
+              <tr><td><code>run_prompt_async(...)</code></td><td>awaitable[CodexExecResult]</td><td>Async prompt wrapper.</td></tr>
+              <tr><td><code>run_with_schema(..., api_key=None, timeout_seconds=None)</code></td><td>CodexExecResult</td><td>Schema-constrained output.</td></tr>
+              <tr><td><code>run_with_schema_async(...)</code></td><td>awaitable[CodexExecResult]</td><td>Async schema wrapper.</td></tr>
+              <tr><td><code>start_thread(..., session_name=None, timeout_seconds=None)</code></td><td>tuple[CodexThreadSession, CodexExecResult]</td><td>Starts JSON thread and optionally records named session metadata.</td></tr>
+              <tr><td><code>start_thread_async(...)</code></td><td>awaitable[tuple[CodexThreadSession, CodexExecResult]]</td><td>Async thread start.</td></tr>
+              <tr><td><code>resume(..., session_name=None, timeout_seconds=None)</code></td><td>CodexExecResult</td><td>Sync continuation.</td></tr>
+              <tr><td><code>resume_async(...)</code></td><td>awaitable[CodexExecResult]</td><td>Async continuation.</td></tr>
+              <tr><td><code>run_live(...)</code> / <code>resume_live(...)</code></td><td>CodexLiveRun</td><td>Sync live streaming with startup retry support.</td></tr>
+              <tr><td><code>run_live_async(...)</code> / <code>resume_live_async(...)</code></td><td>awaitable[AsyncCodexLiveRun]</td><td>Async live streaming with startup retry support.</td></tr>
+            </tbody>
+          </table>
+        </div>
+        <h3>Session APIs</h3>
+        <ul>
+          <li><code>save_session</code>, <code>get_session_id</code>, <code>delete_session</code>, <code>list_sessions</code></li>
+          <li><code>get_session_record</code>, <code>list_session_records</code>, <code>open_session</code></li>
+        </ul>
+      </section>
+      <section class="section" id="telemetry">
+        <h2>Telemetry</h2>
+        <p>Pass <code>event_hook</code> to receive <code>CodexClientEvent</code> records.</p>
+        <pre><code>def on_event(event: CodexClientEvent) -> None:
+    print(event.type, event.operation, event.attempt, event.return_code)
+client = CodexLocalClient(event_hook=on_event)</code></pre>
+        <p>Event types include:</p>
+        <ul>
+          <li><code>attempt.started</code>, <code>attempt.failed</code>, <code>attempt.succeeded</code>, <code>retry.scheduled</code></li>
+          <li><code>live.started</code>, <code>live.startup_failed</code>, <code>live.startup_retried</code>, <code>live.event</code></li>
+          <li><code>session.updated</code></li>
+        </ul>
+      </section>
+      <section class="section" id="live-run">
+        <h2>Live Handles</h2>
+        <ul>
+          <li><code>CodexLiveRun</code>: <code>iter_events()</code>, <code>wait(timeout=None)</code>, <code>result()</code>, <code>terminate()</code>, <code>kill()</code>.</li>
+          <li><code>AsyncCodexLiveRun</code>: async equivalents <code>iter_events()</code>, <code>wait()</code>, and <code>result()</code>.</li>
+        </ul>
+      </section>
+      <section class="section" id="thread-session">
+        <h2>CodexThreadSession</h2>
+        <ul>
+          <li><code>continue_prompt(..., timeout_seconds=None)</code></li>
+          <li><code>continue_prompt_async(..., timeout_seconds=None)</code></li>
+          <li><code>continue_live(...)</code></li>
+          <li><code>continue_live_async(...)</code></li>
+          <li><code>is_last_turn_complete</code> helper property</li>
+        </ul>
+      </section>
+      <section class="section" id="errors">
+        <h2>Errors</h2>
+        <ul>
+          <li><code>CodexError</code> (base)</li>
+          <li><code>CodexNotInstalledError</code> (missing CLI)</li>
+          <li><code>CodexExecFailedError</code> (non-zero with <code>raise_on_error=True</code>)</li>
+        </ul>
+      </section>
+      <footer class="footer">Reference reflects current implementation in <code>codex_local_sdk/</code>.</footer>
+    </main>
+  </div>
+</body>
+</html>

codex_sdk_python/data/docs/html documentation/assets/styles.css ADDED Viewed

@@ -0,0 +1,265 @@
+:root {
+  --bg: #0b0d10;
+  --bg-soft: #12161c;
+  --panel: #151a21;
+  --line: #2b3340;
+  --text: #e7ecf3;
+  --muted: #9aa6b8;
+  --accent: #10a37f;
+  --code-bg: #0f141b;
+}
+* {
+  box-sizing: border-box;
+}
+html,
+body {
+  margin: 0;
+  padding: 0;
+  background: radial-gradient(circle at top right, #172130 0%, var(--bg) 40%);
+  color: var(--text);
+  font-family: "IBM Plex Sans", "Segoe UI", Roboto, Arial, sans-serif;
+  min-height: 100%;
+}
+a {
+  color: #7cc9ff;
+  text-decoration: none;
+}
+a:hover {
+  text-decoration: underline;
+}
+.layout {
+  display: grid;
+  grid-template-columns: 280px minmax(0, 1fr);
+  min-height: 100vh;
+}
+.sidebar {
+  border-right: 1px solid var(--line);
+  background: rgba(7, 10, 14, 0.92);
+  padding: 24px 18px;
+  position: sticky;
+  top: 0;
+  max-height: 100vh;
+  overflow-y: auto;
+}
+.logo {
+  display: block;
+  font-size: 0.76rem;
+  font-weight: 700;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--muted);
+  margin-bottom: 16px;
+}
+.title {
+  font-size: 1.02rem;
+  font-weight: 700;
+  margin: 0 0 4px;
+}
+.subtitle {
+  font-size: 0.86rem;
+  color: var(--muted);
+  margin: 0 0 20px;
+}
+.nav-group {
+  margin-bottom: 16px;
+}
+.nav-group-label {
+  font-size: 0.74rem;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--muted);
+  margin: 0 0 8px;
+}
+.nav-link {
+  display: block;
+  padding: 8px 10px;
+  border-radius: 8px;
+  color: var(--text);
+  font-size: 0.9rem;
+  line-height: 1.25;
+}
+.nav-link.active {
+  background: linear-gradient(90deg, rgba(16, 163, 127, 0.22), rgba(16, 163, 127, 0.08));
+  border: 1px solid rgba(16, 163, 127, 0.34);
+}
+.main {
+  padding: 30px 38px 56px;
+}
+.hero {
+  background: linear-gradient(130deg, rgba(16, 163, 127, 0.16), rgba(26, 32, 43, 0.9));
+  border: 1px solid rgba(16, 163, 127, 0.28);
+  border-radius: 14px;
+  padding: 24px;
+  margin-bottom: 24px;
+}
+.hero h1 {
+  margin: 0 0 10px;
+  font-size: clamp(1.6rem, 2.4vw, 2.2rem);
+}
+.hero p {
+  margin: 0;
+  color: var(--muted);
+  max-width: 70ch;
+}
+.card-grid {
+  display: grid;
+  gap: 14px;
+  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+  margin-bottom: 24px;
+}
+.card {
+  border: 1px solid var(--line);
+  border-radius: 12px;
+  background: var(--panel);
+  padding: 14px;
+}
+.card h3 {
+  margin: 0 0 6px;
+  font-size: 1rem;
+}
+.card p {
+  margin: 0;
+  color: var(--muted);
+  font-size: 0.92rem;
+}
+.section {
+  margin: 28px 0;
+}
+.section h2 {
+  margin: 0 0 10px;
+  font-size: 1.45rem;
+}
+.section h3 {
+  margin: 20px 0 10px;
+  font-size: 1.1rem;
+}
+.section p,
+.section li {
+  color: var(--text);
+  line-height: 1.6;
+}
+.section ul {
+  margin: 0;
+  padding-left: 18px;
+}
+.muted {
+  color: var(--muted);
+}
+.badge {
+  display: inline-block;
+  padding: 3px 8px;
+  border-radius: 99px;
+  border: 1px solid rgba(16, 163, 127, 0.45);
+  color: #b7f1e3;
+  background: rgba(16, 163, 127, 0.12);
+  font-size: 0.75rem;
+  letter-spacing: 0.02em;
+}
+pre {
+  margin: 10px 0 14px;
+  background: var(--code-bg);
+  border: 1px solid var(--line);
+  border-radius: 12px;
+  padding: 14px;
+  overflow: auto;
+}
+code,
+pre {
+  font-family: "IBM Plex Mono", "Cascadia Code", Consolas, monospace;
+  font-size: 0.85rem;
+}
+.table-wrap {
+  overflow: auto;
+  border: 1px solid var(--line);
+  border-radius: 10px;
+}
+table {
+  width: 100%;
+  border-collapse: collapse;
+  min-width: 720px;
+}
+thead {
+  background: #11161e;
+}
+th,
+td {
+  text-align: left;
+  padding: 11px;
+  border-bottom: 1px solid var(--line);
+  vertical-align: top;
+}
+th {
+  color: #d8e2ef;
+  font-size: 0.83rem;
+  letter-spacing: 0.02em;
+}
+td {
+  font-size: 0.88rem;
+}
+.callout {
+  border-left: 4px solid var(--accent);
+  background: rgba(16, 163, 127, 0.1);
+  border-radius: 8px;
+  padding: 12px 12px 12px 14px;
+  margin: 14px 0;
+}
+.footer {
+  margin-top: 42px;
+  color: var(--muted);
+  font-size: 0.83rem;
+}
+@media (max-width: 900px) {
+  .layout {
+    grid-template-columns: 1fr;
+  }
+  .sidebar {
+    position: relative;
+    max-height: none;
+    border-right: 0;
+    border-bottom: 1px solid var(--line);
+  }
+  .main {
+    padding: 22px 18px 34px;
+  }
+}

codex_sdk_python/data/docs/html documentation/examples.html ADDED Viewed

@@ -0,0 +1,203 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Examples Cookbook - SpawnCodex Python SDK Docs</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600;700&display=swap" rel="stylesheet">
+  <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet">
+  <link href="assets/styles.css" rel="stylesheet">
+</head>
+<body>
+  <div class="layout">
+    <aside class="sidebar">
+      <span class="logo">SpawnCodex</span>
+      <h1 class="title">Python SDK Docs</h1>
+      <p class="subtitle">Local Codex non-interactive client</p>
+      <div class="nav-group">
+        <p class="nav-group-label">Overview</p>
+        <a class="nav-link" href="index.html">Home</a>
+        <a class="nav-link" href="getting-started.html">Getting Started</a>
+        <a class="nav-link" href="api-reference.html">API Reference</a>
+        <a class="nav-link" href="live-threads.html">Live Runs & Threads</a>
+        <a class="nav-link active" href="examples.html">Examples Cookbook</a>
+        <a class="nav-link" href="testing-and-quality.html">Testing & Quality</a>
+      </div>
+      <div class="nav-group">
+        <p class="nav-group-label">On This Page</p>
+        <a class="nav-link" href="#official-examples">Repository Examples</a>
+        <a class="nav-link" href="#quick-recipes">Quick Recipes</a>
+        <a class="nav-link" href="#async-pattern">Async Pattern</a>
+        <a class="nav-link" href="#retry-pattern">Retry Pattern</a>
+        <a class="nav-link" href="#persistent-pattern">Persistent Session Pattern</a>
+        <a class="nav-link" href="#telemetry-pattern">Telemetry Pattern</a>
+      </div>
+    </aside>
+    <main class="main">
+      <section class="hero">
+        <span class="badge">Cookbook</span>
+        <h1>Examples and Integration Recipes</h1>
+        <p>
+          Ready-to-run snippets from <code>examples/</code> and integration patterns for sync/async, retries, and persistent sessions.
+        </p>
+      </section>
+      <section class="section" id="official-examples">
+        <h2>Examples in This Repository</h2>
+        <div class="table-wrap">
+          <table>
+            <thead>
+              <tr><th>File</th><th>Main Method</th><th>Purpose</th></tr>
+            </thead>
+            <tbody>
+              <tr><td><code>examples/run_simple.py</code></td><td><code>client.run()</code></td><td>Basic prompt execution and final message output.</td></tr>
+              <tr><td><code>examples/run_json_events.py</code></td><td><code>json_output=True</code></td><td>Collect events, thread id, turn status, usage.</td></tr>
+              <tr><td><code>examples/run_live_stream.py</code></td><td><code>client.run_live()</code></td><td>Stream JSON events from a running sync process.</td></tr>
+              <tr><td><code>examples/run_thread_session.py</code></td><td><code>start_thread()</code></td><td>Create session and continue with follow-up prompts.</td></tr>
+              <tr><td><code>examples/run_with_schema.py</code></td><td><code>run_with_schema()</code></td><td>Constrain output to JSON schema and parse final JSON.</td></tr>
+              <tr><td><code>examples/run_async.py</code></td><td><code>run_async()</code> + <code>run_live_async()</code></td><td>Async run plus async event streaming.</td></tr>
+              <tr><td><code>examples/run_persistent_session_store.py</code></td><td><code>JsonFileSessionStore</code></td><td>Persist named sessions and resume by name.</td></tr>
+            </tbody>
+          </table>
+        </div>
+      </section>
+      <section class="section" id="quick-recipes">
+        <h2>Quick Recipes</h2>
+        <h3>1. Plain Prompt (Minimal)</h3>
+<pre><code>from codex_local_sdk import CodexLocalClient
+client = CodexLocalClient()
+result = client.run_prompt("Summarize this project in 5 bullets.")
+print(result.final_message)</code></pre>
+        <h3>2. Explicit Request with Sandbox</h3>
+<pre><code>from codex_local_sdk import CodexExecRequest, CodexLocalClient, SandboxMode
+client = CodexLocalClient()
+result = client.run(
+    CodexExecRequest(
+        prompt="Find architecture risks.",
+        sandbox=SandboxMode.READ_ONLY,
+        skip_git_repo_check=True,
+    ),
+    timeout_seconds=120,
+)</code></pre>
+      </section>
+      <section class="section" id="async-pattern">
+        <h2>Async Pattern</h2>
+<pre><code>import asyncio
+from codex_local_sdk import CodexExecRequest, CodexLocalClient
+async def main() -> None:
+    client = CodexLocalClient()
+    result = await client.run_async(CodexExecRequest(prompt="Analyze repo"), timeout_seconds=120)
+    print(result.final_message)
+    live = await client.run_live_async(CodexExecRequest(prompt="Stream repo analysis", json_output=True))
+    async for event in live.iter_events():
+        print(event.type)
+    final = await live.wait()
+    print(final.turn_status)
+asyncio.run(main())</code></pre>
+      </section>
+      <section class="section" id="retry-pattern">
+        <h2>Retry/Backoff Pattern</h2>
+<pre><code>from codex_local_sdk import CodexExecRequest, CodexLocalClient, RetryPolicy
+client = CodexLocalClient(
+    retry_policy=RetryPolicy(
+        max_attempts=3,
+        initial_backoff_seconds=0.5,
+        backoff_multiplier=2.0,
+        max_backoff_seconds=4.0,
+        retry_on_exit_codes=(7, 9),
+        jitter_ratio=0.2,
+        max_total_retry_seconds=15.0,
+        retry_on_timeouts=True,
+    )
+)
+result = client.run(CodexExecRequest(prompt="Run resiliently"), timeout_seconds=30)
+print(result.return_code, result.ok)</code></pre>
+      </section>
+      <section class="section" id="persistent-pattern">
+        <h2>Persistent Session Pattern</h2>
+<pre><code>from codex_local_sdk import CodexLocalClient, JsonFileSessionStore, SandboxMode
+client = CodexLocalClient(session_store=JsonFileSessionStore(".codex_sessions.json"))
+session, first = client.start_thread(
+    prompt="Create migration plan",
+    sandbox=SandboxMode.READ_ONLY,
+    session_name="migration-plan",
+)
+print(session.session_id, first.turn_status)
+second = client.resume(
+    prompt="Continue with phase 1 tasks",
+    session_name="migration-plan",
+    last=False,
+    json_output=True,
+    timeout_seconds=120,
+)
+print(second.final_message)
+same_session = client.open_session("migration-plan")
+third = same_session.continue_prompt("Continue with test strategy", json_output=True)
+print(third.turn_status)</code></pre>
+      </section>
+      <section class="section" id="telemetry-pattern">
+        <h2>Telemetry Hook Pattern</h2>
+<pre><code>from codex_local_sdk import CodexClientEvent, CodexExecRequest, CodexLocalClient
+def on_event(event: CodexClientEvent) -> None:
+    print(event.type, event.operation, event.attempt, event.return_code)
+client = CodexLocalClient(event_hook=on_event)
+client.run(CodexExecRequest(prompt="Analyze repo"), timeout_seconds=60)</code></pre>
+      </section>
+      <section class="section">
+        <h2>Service Integration Skeleton</h2>
+<pre><code>class CodexService:
+    def __init__(self) -> None:
+        self.client = CodexLocalClient(default_cwd="/workspace/project")
+    def analyze_repo(self) -> str:
+        result = self.client.run_prompt(
+            "Provide architecture summary and top 5 technical risks.",
+            json_output=True,
+        )
+        return result.final_message or ""
+    async def analyze_repo_async(self) -> str:
+        result = await self.client.run_async(
+            CodexExecRequest(prompt="Provide async architecture summary", json_output=True)
+        )
+        return result.final_message or ""</code></pre>
+      </section>
+      <footer class="footer">
+        For method-level details, see <a href="api-reference.html">API Reference</a>.
+      </footer>
+    </main>
+  </div>
+</body>
+</html>