pi-sidecar-client 0.1.0.dev1__tar.gz

pi_sidecar_client-0.1.0.dev1/LICENSE

@@ -0,0 +1,191 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 myk-org
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

pi_sidecar_client-0.1.0.dev1/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: pi-sidecar-client
+Version: 0.1.0.dev1
+Summary: Python client for the Pi SDK sidecar service
+License: Apache-2.0
+Project-URL: Repository, https://github.com/myk-org/pi-sidecar
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: python-simple-logger
+Dynamic: license-file

pi_sidecar_client-0.1.0.dev1/README.md

@@ -0,0 +1,158 @@
+# pi-sidecar
+
+A standalone HTTP service that wraps the [Pi coding agent SDK](https://www.npmjs.com/package/@earendil-works/pi-coding-agent), exposing AI sessions over a simple JSON API. Ships with a Python client for easy integration.
+
+## Packages
+
+| Package | Language | Install |
+|---------|----------|---------|
+| `@myk-org/pi-sidecar` | TypeScript | `npm install @myk-org/pi-sidecar` |
+| `pi-sidecar-client` | Python ≥ 3.10 | `pip install pi-sidecar-client` |
+
+## Provider Support
+
+| Provider | Sidecar name | Required env vars / config |
+|----------|-------------|---------------------------|
+| Gemini | `google` | `GOOGLE_API_KEY` or Application Default Credentials |
+| Claude (Vertex AI) | `google-vertex-claude` | `GOOGLE_APPLICATION_CREDENTIALS`, Vertex extension (`SIDECAR_VERTEX_EXTENSION_PATH`) |
+| Claude (API key) | `anthropic` | `ANTHROPIC_API_KEY` |
+| Cursor (via acpx) | `acpx-cursor` | `ACPX_AGENTS=cursor`, acpx CLI on `$PATH`, ACPX extension (`SIDECAR_ACPX_EXTENSION_PATH`) |
+
+> **Note:** The Python client accepts friendly provider names (`gemini`, `claude`, `cursor`) and maps them internally to sidecar provider names (`google`, `google-vertex-claude`, `acpx-cursor`).
+
+## HTTP API
+
+All endpoints accept/return JSON. Default base URL: `http://127.0.0.1:9100`.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/health` | Returns `{"status":"ok","sessions":N}`. 503 while model discovery is in progress. |
+| `GET` | `/models` | List all discovered models. |
+| `POST` | `/models/refresh` | Re-run model discovery and return updated list. |
+| `POST` | `/sessions` | Create a session. Body: `{provider, model, system_prompt, cwd?, custom_tools?}` → `{session_id}` |
+| `POST` | `/sessions/:id/prompt` | Send a message. Body: `{message}` → `{text, usage}` |
+| `POST` | `/sessions/:id/abort` | Abort an in-progress prompt. |
+| `DELETE` | `/sessions/:id` | Delete a session and free resources. |
+
+## TypeScript Usage
+
+### Programmatic
+
+```ts
+import { startSidecar } from "@myk-org/pi-sidecar";
+
+startSidecar({ port: 9100, host: "127.0.0.1" });
+```
+
+### Standalone
+
+```bash
+npm run build
+node dist/server.js          # listens on 127.0.0.1:9100
+SIDECAR_PORT=9200 node dist/server.js   # custom port
+DEV_MODE=true node dist/server.js       # bind 0.0.0.0
+```
+
+## Python Client Usage
+
+### Single-shot call (auto-cleanup)
+
+```python
+from pi_sidecar_client import call_ai_once
+
+result = await call_ai_once(
+    "Summarize this log file",
+    ai_provider="gemini",
+    ai_model="gemini-2.5-flash",
+    system_prompt="You are a log analyst.",
+)
+print(result.text)
+```
+
+### Multi-turn conversation (session reuse)
+
+```python
+from pi_sidecar_client import call_ai, get_sidecar_client
+
+r1 = await call_ai("Analyze this failure", ai_provider="claude", ai_model="claude-sonnet-4-20250514")
+r2 = await call_ai("Now suggest a fix", session_id=r1.session_id)
+
+# Clean up when done
+await get_sidecar_client().delete_session(r2.session_id)
+```
+
+### Direct client usage
+
+```python
+from pi_sidecar_client import SidecarClient
+
+client = SidecarClient("http://127.0.0.1:9100")
+try:
+    sid = await client.create_session(
+        provider="google",
+        model="gemini-2.5-flash",
+        system_prompt="You are helpful.",
+    )
+    result = await client.prompt(sid, "Hello!")
+    print(result.text)
+    await client.delete_session(sid)
+finally:
+    await client.close()
+```
+
+### List models
+
+```python
+from pi_sidecar_client import list_models
+
+all_models = await list_models()
+gemini_only = await list_models(provider="gemini")
+```
+
+## Testing
+
+**TypeScript sidecar:**
+
+```bash
+npm install
+npm test
+```
+
+**Python client:**
+
+```bash
+pip install -e '.[tests]'
+pytest
+```
+
+## Examples
+
+See the [`examples/`](examples/) directory for usage patterns:
+
+| File | Description |
+|------|-------------|
+| `basic_prompt.py` | Single-shot AI call with `call_ai_once()` |
+| `multi_turn.py` | Multi-turn conversation with session reuse |
+| `list_models.py` | Discover available models by provider |
+| `health_check.py` | Verify sidecar is running and ready |
+| `parallel_tasks.py` | Run multiple AI calls with concurrency limiting |
+| `usage_tracking.py` | Track token usage with a pluggable callback |
+| `start-sidecar.ts` | Start the sidecar programmatically (TypeScript) |
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SIDECAR_PORT` | `9100` | HTTP listen port |
+| `SIDECAR_URL` | `http://127.0.0.1:9100` | Base URL used by the Python client |
+| `DEV_MODE` | `false` | Set `true` to bind `0.0.0.0` instead of `127.0.0.1` |
+| `ACPX_AGENTS` | *(empty)* | Comma-separated list of acpx agents to discover models from (e.g. `cursor`) |
+| `SIDECAR_ACPX_EXTENSION_PATH` | auto-resolved via `require.resolve` from `pi-orchestrator-config` | Path to the acpx provider extension |
+| `SIDECAR_VERTEX_EXTENSION_PATH` | auto-resolved via `require.resolve` from `node_modules` | Path to the Vertex Claude extension |
+| `SIDECAR_WATCHDOG_URL` | *(disabled)* | Health endpoint URL for watchdog monitoring. When set, the sidecar monitors this URL and shuts down if it becomes unresponsive. Disabled by default for standalone usage. |
+
+## Architecture Notes
+
+- **Watchdog**: opt-in health-check poller activated via `SIDECAR_WATCHDOG_URL`. When enabled, monitors the given URL and shuts down the sidecar after 30 s of consecutive failures. Disabled by default for standalone usage.
+- **Stale session cleanup**: sessions idle for >1 hour are automatically disposed (checked every 10 minutes).
+- **Model discovery**: runs at startup; `/health` returns 503 until complete.

pi_sidecar_client-0.1.0.dev1/pi_sidecar_client/__init__.py

@@ -0,0 +1,352 @@
+import asyncio
+import inspect
+import os
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+from simple_logger.logger import get_logger
+
+logger = get_logger(name=__name__, level=os.environ.get("LOG_LEVEL", "INFO"))
+
+SIDECAR_URL = os.environ.get("SIDECAR_URL", "http://127.0.0.1:9100")
+
+__all__ = [
+    "AIResult",
+    "AITokenUsage",
+    "SidecarClient",
+    "call_ai",
+    "call_ai_once",
+    "check_sidecar_available",
+    "get_sidecar_client",
+    "list_models",
+    "run_parallel_with_limit",
+    "set_usage_recorder",
+]
+
+
+@dataclass
+class AITokenUsage:
+    """Token usage data from an AI call."""
+
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_read_tokens: int = 0
+    cache_write_tokens: int = 0
+    cost_usd: float | None = None
+    duration_ms: int | None = None
+    provider: str = ""
+    model: str = ""
+    session_id: str = ""
+
+
+# Module-level callback — consumers register their storage function
+_usage_recorder: Callable | None = None
+
+
+def set_usage_recorder(callback: Callable) -> None:
+    """Register a callback for recording AI token usage.
+
+    The callback signature:
+        async def recorder(*, request_id, result, call_type, prompt_chars, ai_provider, ai_model)
+    """
+    global _usage_recorder
+    _usage_recorder = callback
+
+
+@dataclass
+class AIResult:
+    """Result from an AI call."""
+
+    success: bool
+    text: str
+    usage: AITokenUsage | None = None
+    session_id: str | None = None
+
+    async def record_usage(
+        self,
+        *,
+        request_id: str,
+        call_type: str,
+        prompt_chars: int = 0,
+        ai_provider: str = "",
+        ai_model: str = "",
+    ) -> None:
+        """Record token usage via the registered callback. Best-effort — never raises."""
+        if not _usage_recorder:
+            return
+        try:
+            maybe_coro = _usage_recorder(
+                request_id=request_id,
+                result=self,
+                call_type=call_type,
+                prompt_chars=prompt_chars,
+                ai_provider=ai_provider,
+                ai_model=ai_model,
+            )
+            if inspect.isawaitable(maybe_coro):
+                await maybe_coro
+        except Exception:
+            logger.debug("Failed to record usage", exc_info=True)
+
+
+# Provider mapping: friendly provider names → sidecar provider names
+_PROVIDER_MAP = {
+    "cursor": "acpx-cursor",
+    "claude": "google-vertex-claude",
+    "gemini": "google",
+}
+
+
+def _map_provider_model(provider: str, model: str) -> tuple[str, str]:
+    """Map friendly provider/model names to sidecar provider/model."""
+    sidecar_provider = _PROVIDER_MAP.get(provider, provider)
+    sidecar_model = model
+    # Cursor models need the cursor: prefix
+    if sidecar_provider == "acpx-cursor" and not model.startswith("cursor:"):
+        sidecar_model = f"cursor:{model}"
+    return sidecar_provider, sidecar_model
+
+
+class SidecarClient:
+    """HTTP client for the Pi SDK sidecar service."""
+
+    def __init__(self, base_url: str = SIDECAR_URL):
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.AsyncClient(base_url=self._base_url, timeout=600.0)
+
+    async def health(self) -> dict:
+        """Check sidecar health."""
+        resp = await self._client.get("/health")
+        resp.raise_for_status()
+        return resp.json()
+
+    async def get_models(self) -> list[dict]:
+        """Get available models."""
+        resp = await self._client.get("/models")
+        resp.raise_for_status()
+        return resp.json().get("models", [])
+
+    async def refresh_models(self) -> list[dict]:
+        """Trigger model discovery and return updated list."""
+        resp = await self._client.post("/models/refresh")
+        resp.raise_for_status()
+        return resp.json().get("models", [])
+
+    async def create_session(
+        self,
+        *,
+        provider: str,
+        model: str,
+        system_prompt: str,
+        cwd: str = "/tmp",
+        custom_tools: list | None = None,
+    ) -> str:
+        """Create a new AI session. Returns session_id."""
+        sidecar_provider, sidecar_model = _map_provider_model(provider, model)
+        body: dict[str, Any] = {
+            "provider": sidecar_provider,
+            "model": sidecar_model,
+            "system_prompt": system_prompt,
+            "cwd": cwd,
+        }
+        if custom_tools:
+            body["custom_tools"] = custom_tools
+        resp = await self._client.post("/sessions", json=body)
+        resp.raise_for_status()
+        return resp.json()["session_id"]
+
+    async def prompt(self, session_id: str, message: str, timeout: float | None = None) -> AIResult:
+        """Send a message to a session. Returns AIResult."""
+        request_timeout = timeout or self._client.timeout
+        resp = await self._client.post(
+            f"/sessions/{session_id}/prompt",
+            json={"message": message},
+            timeout=request_timeout,
+        )
+        if resp.status_code != 200:
+            try:
+                payload = resp.json()
+                error = payload.get("error", resp.text) if isinstance(payload, dict) else resp.text
+            except ValueError:
+                error = resp.text or f"HTTP {resp.status_code}"
+            return AIResult(success=False, text=error)
+
+        data = resp.json()
+        usage_data = data.get("usage", {})
+        usage = AITokenUsage(
+            input_tokens=usage_data.get("input_tokens", 0),
+            output_tokens=usage_data.get("output_tokens", 0),
+            cache_read_tokens=usage_data.get("cache_read_tokens", 0),
+            cache_write_tokens=usage_data.get("cache_write_tokens", 0),
+            cost_usd=usage_data.get("cost_usd"),
+            duration_ms=usage_data.get("duration_ms"),
+        )
+        return AIResult(
+            success=True,
+            text=data.get("text", ""),
+            usage=usage,
+        )
+
+    async def abort(self, session_id: str) -> None:
+        """Abort an in-progress prompt."""
+        resp = await self._client.post(f"/sessions/{session_id}/abort")
+        resp.raise_for_status()
+
+    async def delete_session(self, session_id: str) -> None:
+        """Delete a session."""
+        resp = await self._client.delete(f"/sessions/{session_id}")
+        resp.raise_for_status()
+
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        await self._client.aclose()
+
+
+# Singleton client
+_client: SidecarClient | None = None
+
+
+def get_sidecar_client() -> SidecarClient:
+    """Get the singleton sidecar client."""
+    global _client
+    if _client is None:
+        _client = SidecarClient()
+    return _client
+
+
+# --- Convenience functions for single-shot AI calls ---
+
+
+async def call_ai(
+    prompt: str,
+    *,
+    ai_provider: str = "",
+    ai_model: str = "",
+    cwd: str | None = None,
+    system_prompt: str = "",
+    ai_cli_timeout: int | None = None,
+    session_id: str | None = None,
+    custom_tools: list | None = None,
+) -> AIResult:
+    """Call AI via the sidecar.
+
+    Creates a new session (or reuses *session_id*), sends the prompt,
+    and returns the result with session_id attached.
+
+    Session lifecycle:
+    - Caller is responsible for deleting sessions when done.
+    - For single-shot calls, use ``call_ai_once(...)``
+      or call ``client.delete_session()`` manually after.
+    - For multi-turn (peer debate), pass ``session_id`` from the
+      previous result to continue the conversation.
+    """
+    client = get_sidecar_client()
+    created_session = False
+    try:
+        if not session_id:
+            session_id = await client.create_session(
+                provider=ai_provider,
+                model=ai_model,
+                system_prompt=system_prompt or "You are a helpful assistant.",
+                cwd=cwd or "/tmp",
+                custom_tools=custom_tools,
+            )
+            created_session = True
+        # Convert minutes to seconds for httpx timeout
+        timeout = ai_cli_timeout * 60.0 if ai_cli_timeout else None
+        result = await client.prompt(session_id, prompt, timeout=timeout)
+        # Attach session_id to result so callers can reuse or clean up
+        result.session_id = session_id
+        return result
+    except Exception as e:
+        logger.error("Sidecar call failed: %s", e)
+        # Clean up session if WE created it and the prompt failed
+        cleanup_succeeded = False
+        if created_session and session_id:
+            try:
+                await client.delete_session(session_id)
+                cleanup_succeeded = True
+            except Exception:
+                logger.debug("Failed to cleanup leaked session %s", session_id, exc_info=True)
+        return AIResult(
+            success=False,
+            text=str(e),
+            session_id=None if cleanup_succeeded else session_id,
+        )
+
+
+async def call_ai_once(
+    prompt: str,
+    *,
+    ai_provider: str = "",
+    ai_model: str = "",
+    cwd: str | None = None,
+    system_prompt: str = "",
+    ai_cli_timeout: int | None = None,
+    custom_tools: list | None = None,
+) -> AIResult:
+    """Single-shot AI call with automatic session cleanup.
+
+    Creates a session, sends the prompt, and always deletes the session.
+    Use this for one-off calls (analysis, bug creation, etc.).
+    Use ``call_ai`` directly for multi-turn conversations (peer debate).
+    """
+    result = await call_ai(
+        prompt,
+        ai_provider=ai_provider,
+        ai_model=ai_model,
+        cwd=cwd,
+        system_prompt=system_prompt,
+        ai_cli_timeout=ai_cli_timeout,
+        custom_tools=custom_tools,
+    )
+    # Always clean up — this is a single-shot call
+    if result.session_id:
+        try:
+            await get_sidecar_client().delete_session(result.session_id)
+            result.session_id = None  # Clear so caller doesn't try to reuse
+        except Exception:
+            logger.debug("Failed to cleanup session %s after call_ai_once", result.session_id, exc_info=True)
+            # Preserve session_id so caller can retry cleanup
+    return result
+
+
+async def list_models(provider: str = "") -> list[dict]:
+    """List available models, optionally filtered by provider."""
+    client = get_sidecar_client()
+    models = await client.get_models()
+    if provider:
+        sidecar_provider = _PROVIDER_MAP.get(provider, provider)
+        models = [m for m in models if m.get("provider") == sidecar_provider]
+    return models
+
+
+async def check_sidecar_available() -> tuple[bool, str]:
+    """Check if the sidecar service is available and ready."""
+    try:
+        client = get_sidecar_client()
+        resp = await client._client.get("/health")
+        data = resp.json()
+        if resp.status_code == 200 and data.get("status") == "ok":
+            return True, "Sidecar is ready"
+        if resp.status_code == 503 and data.get("status") == "starting":
+            return False, f"Sidecar starting: {data.get('message', 'model discovery in progress')}"
+        return False, f"Sidecar unhealthy (HTTP {resp.status_code}): {data}"
+    except Exception as e:
+        return False, f"Sidecar unavailable: {e}"
+
+
+async def run_parallel_with_limit(
+    tasks: list,
+    max_concurrency: int = 5,
+) -> list:
+    """Run async tasks in parallel with concurrency limit."""
+    semaphore = asyncio.Semaphore(max_concurrency)
+
+    async def limited(coro):
+        async with semaphore:
+            return await coro
+
+    return await asyncio.gather(*(limited(t) for t in tasks), return_exceptions=True)

pi_sidecar_client-0.1.0.dev1/pi_sidecar_client.egg-info/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: pi-sidecar-client
+Version: 0.1.0.dev1
+Summary: Python client for the Pi SDK sidecar service
+License: Apache-2.0
+Project-URL: Repository, https://github.com/myk-org/pi-sidecar
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: python-simple-logger
+Dynamic: license-file

pi_sidecar_client-0.1.0.dev1/pi_sidecar_client.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+pyproject.toml
+pi_sidecar_client/__init__.py
+pi_sidecar_client.egg-info/PKG-INFO
+pi_sidecar_client.egg-info/SOURCES.txt
+pi_sidecar_client.egg-info/dependency_links.txt
+pi_sidecar_client.egg-info/requires.txt
+pi_sidecar_client.egg-info/top_level.txt

pi_sidecar_client-0.1.0.dev1/pi_sidecar_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pi_sidecar_client-0.1.0.dev1/pi_sidecar_client.egg-info/requires.txt

@@ -0,0 +1,2 @@
+httpx>=0.27
+python-simple-logger

pi_sidecar_client-0.1.0.dev1/pi_sidecar_client.egg-info/top_level.txt

@@ -0,0 +1 @@
+pi_sidecar_client

pi_sidecar_client-0.1.0.dev1/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pi-sidecar-client"
+version = "0.1.0.dev1"
+description = "Python client for the Pi SDK sidecar service"
+license = {text = "Apache-2.0"}
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.27", "python-simple-logger"]
+
+[project.urls]
+Repository = "https://github.com/myk-org/pi-sidecar"
+
+[tool.setuptools.packages.find]
+include = ["pi_sidecar_client*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests/test_python"]
+
+[tool.ruff]
+preview = true
+line-length = 120
+fix = true
+output-format = "grouped"
+
+[tool.ruff.format]
+exclude = [".git", ".venv", ".mypy_cache", ".tox", "__pycache__"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "PLC0415", "ARG", "RUF059"]
+
+[tool.ruff.lint.per-file-ignores]
+"*" = ["E501"]
+"/*tests/*" = ["ARG"]
+
+[tool.mypy]
+check_untyped_defs = false
+disallow_any_generics = false
+disallow_incomplete_defs = true
+disallow_untyped_defs = false
+no_implicit_optional = true
+show_error_codes = true
+warn_unused_ignores = true
+strict_equality = true
+extra_checks = true
+warn_unused_configs = true
+warn_redundant_casts = true
+
+[[tool.mypy.overrides]]
+module = "simple_logger.*"
+ignore_missing_imports = true
+
+[dependency-groups]
+dev = [
+    "pytest",
+    "pytest-asyncio",
+]

pi_sidecar_client-0.1.0.dev1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+