pal-runtime 0.1.0__tar.gz

pal_runtime-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 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
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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.

pal_runtime-0.1.0/PKG-INFO

@@ -0,0 +1,373 @@
+Metadata-Version: 2.4
+Name: pal-runtime
+Version: 0.1.0
+Summary: Python SDK for PAL (Personalized Agentic Layer) — the PAL Runtime
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/dshakes/pal
+Project-URL: Source, https://github.com/dshakes/pal/tree/master/packages/sdk-python
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Requires-Dist: grpcio>=1.62
+Requires-Dist: protobuf>=5.0
+Requires-Dist: opentelemetry-api>=1.20
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Provides-Extra: deepagents
+Requires-Dist: deepagents>=0.6; extra == "deepagents"
+Dynamic: license-file
+
+# pal-runtime (Python)
+
+The official Python SDK for [PAL](https://github.com/dshakes/pal) — the
+open-source runtime for production AI agents with VPC deployment, pre-run cost
+forecasts, policy budgets, and eval-in-CI.
+
+Python 3.11+. Async-first (httpx + asyncio). Full parity with the TypeScript SDK's
+HTTP surface.
+
+---
+
+## Install
+
+Registry packages are not published yet. The distribution is named `pal-runtime`; do not
+`pip install pal-sdk` (that PyPI name belongs to an unrelated project). Install from the repo:
+
+```bash
+pip install "path/to/pal/packages/sdk-python"          # add [deepagents] for the extra below
+# or in CI:
+pip install "git+https://github.com/dshakes/pal.git#subdirectory=packages/sdk-python"
+```
+
+The import package is `pal` (`from pal import PalClient`); the CLI entry point is `pal-runner`.
+
+Dependencies pulled in automatically: `httpx>=0.27`, `pydantic>=2.0`, `grpcio>=1.62`,
+`protobuf>=5.0`, `opentelemetry-api>=1.20`.
+
+Optional extras:
+
+| Extra        | Pulls in           | For                                                        |
+| ------------ | ------------------ | ---------------------------------------------------------- |
+| `deepagents` | `deepagents>=0.6`  | Run a LangChain deepagents agent on a PAL microVM — see [deepagents integration](#deepagents-integration) |
+
+---
+
+## Quick start
+
+```python
+import asyncio
+import os
+from pal import PalClient
+
+async def main():
+    async with PalClient(
+        api_key=os.environ["PAL_API_KEY"],
+        # base_url defaults to PAL_API_URL, else http://localhost:8080
+        # or set PAL_API_URL for a self-hosted instance
+    ) as client:
+
+        # 1. Create an agent
+        agent = await client.agents.create(name="triage", description="Classifies support emails")
+
+        # 2. Run it
+        run = await client.runs.create(agent="triage", input={"email": "my invoice is wrong"})
+        print(run.status, run.output)
+
+        # 3. Stream events in real time
+        async for event in client.runs.events(run.id):
+            print(event.kind, event.data)
+
+asyncio.run(main())
+```
+
+---
+
+## Client constructor
+
+```python
+PalClient(
+    base_url: str | None = None,    # default: PAL_API_URL or http://localhost:8080
+    api_key: str | None = None,     # default: PAL_API_KEY
+    *,
+    timeout: float = 30.0,          # per-request timeout in seconds
+    route_strategy: str | None = None,  # default: PAL_ROUTE_STRATEGY or "auto"
+)
+```
+
+Use as a context manager (`async with PalClient(...) as client`) to ensure the
+underlying httpx connection pool is closed. Call `await client.close()` manually if
+not using a context manager.
+
+---
+
+## Env vars
+
+| Var | Purpose |
+|---|---|
+| `PAL_API_URL` | Base URL of the control-plane API. Default `http://localhost:8080`; set it to your control plane |
+| `PAL_API_KEY` | Bearer token issued by `POST /auth/login` or the API-keys settings page |
+| `PAL_ROUTE_STRATEGY` | One of `auto`, `cheap`, `best`, `fast`. Sent as `X-Pal-Route-Strategy`. Default `auto` |
+
+---
+
+## API reference
+
+### Agents — `client.agents`
+
+```python
+# Create
+agent: AgentInfo = await client.agents.create(name="my-agent", description="...", labels={})
+
+# Get
+agent: AgentInfo = await client.agents.get("my-agent")
+
+# List
+resp: AgentListResponse = await client.agents.list(page_size=50, page_token=None)
+# resp.agents: list[AgentInfo]
+# resp.next_page_token: str | None
+
+# Delete
+await client.agents.delete("my-agent")
+```
+
+### Runs — `client.runs`
+
+```python
+# Create (returns Run)
+run: Run = await client.runs.create(
+    agent="triage",
+    input={"email": "..."},
+    labels={},
+    idempotency_key=None,   # optional; derived from (run_id, step_id, attempt) in the engine
+)
+
+# Create with streaming (returns async iterator of StreamEvent)
+stream = await client.runs.create(agent="triage", input={...}, stream=True)
+async for event in stream:
+    print(event.kind, event.data)
+
+# Get, list, cancel
+run: Run = await client.runs.get(run_id)
+resp: RunListResponse = await client.runs.list(agent="triage", status="completed", page_size=50)
+run: Run = await client.runs.cancel(run_id, reason="user cancelled")
+
+# Stream events from a completed or live run
+async for event in client.runs.events(run_id, from_seq=0, live=True):
+    print(event.kind, event.data)
+
+# Send a signal to a paused run (workflow approval / step_signal)
+await client.runs.signal(run_id, name="approved", value={"comment": "lgtm"})
+```
+
+### Sessions — `client.sessions`
+
+```python
+# Create an interactive multi-turn session
+session: Session = await client.sessions.create(agent="my-agent", metadata={})
+
+# Send a message and get the synchronous response
+msg: SessionMessage = await client.sessions.send_message(session_id, content="hello", role="user")
+
+# Stream session events (SSE)
+async for event in client.sessions.stream_events(session_id, from_seq=0):
+    print(event)
+
+# Get, list, close
+session = await client.sessions.get(session_id)
+resp: SessionListResponse = await client.sessions.list(agent="my-agent", status="active")
+await client.sessions.close(session_id)
+```
+
+### Connectors — `client.connectors`
+
+```python
+# List installed connectors
+resp: ConnectorListResponse = await client.connectors.list()
+
+# Execute a connector action (e.g. send a Slack message)
+result: ConnectorResult = await client.connectors.execute(
+    "slack",
+    "send_message",
+    params={"channel": "#general", "text": "Hello from PAL!"},
+)
+
+# List available actions for a connector
+actions: list[dict] = await client.connectors.list_actions("slack")
+```
+
+---
+
+## Building an agent (decorator style)
+
+```python
+from pal import agent, step, tool
+from pal.types import AgentContext
+
+@agent("researcher", model="reasoning-large", description="Deep research agent")
+async def researcher(input: dict, ctx: AgentContext) -> dict:
+    # step() is durable: result is journalled and replayed on restart
+    results = await step(
+        "search",
+        lambda: ctx.tools.web.search(input["query"]),
+    )
+    # parallel fan-out
+    summaries = await step_map(
+        "summarize",
+        results[:5],
+        lambda item, i: ctx.llm.complete(prompt=f"Summarize: {item}"),
+        concurrency=3,
+    )
+    return {"summaries": summaries}
+```
+
+### Step primitives
+
+| Function | Behaviour |
+|---|---|
+| `await step(name, fn, *, retry, timeout)` | Single durable step. `fn` is an async callable. |
+| `await step_map(name, items, fn, *, concurrency, retry, timeout)` | Fan-out over a list; each item gets its own journal entry `name[i]` |
+| `await step_race(name, fns, *, retry, timeout)` | Run multiple callables concurrently; return the first result, cancel the rest |
+| `await step_sleep(name, duration)` | Durable sleep. Duration strings: `"30s"`, `"5m"`, `"2h"` |
+| `await step_signal(name, *, timeout)` | Wait for an external signal. Only functional in the PAL production runtime |
+
+In local / dev mode all step primitives execute the function directly (no
+journalling). The production runtime installs a journal-aware runner via
+`set_step_runtime()`.
+
+### Built-in tools
+
+```python
+from pal.tools import tool   # singleton registry
+
+@agent("worker", tools=[tool.web, tool.python])
+async def worker(input: dict, ctx: AgentContext) -> dict:
+    html = await ctx.tools.web.fetch("https://example.com")
+    ...
+```
+
+Available: `tool.web`, `tool.python`, `tool.fs`, `tool.browser`. `tool.all()` returns
+all four.
+
+### Class-based pattern
+
+```python
+from pal.agent import PalAgent
+from pal.types import AgentContext
+
+class MyAgent(PalAgent):
+    name = "my-agent"
+    model = "auto"
+
+    async def run(self, input: dict, ctx: AgentContext) -> dict:
+        ...
+```
+
+---
+
+## Errors
+
+All errors inherit from `PalError`.
+
+| Exception | Raised when |
+|---|---|
+| `PalApiError(status_code, body)` | HTTP response is non-2xx |
+| `PalStepError(name, reason)` | Step execution fails |
+| `PalLlmError` | LLM call fails (budget, provider, timeout) |
+| `PalTimeoutError(name, duration)` | `step()` / `step_sleep()` timeout exceeded |
+| `PalValidationError` | Invalid agent name or config |
+
+---
+
+## Running an agent locally
+
+```bash
+python -m pal.runtime.runner --agent hello-world --input '{"name": "World"}'
+```
+
+The `pal-runner` entry point (installed by `pip install`) does the same:
+
+```bash
+pal-runner --agent hello-world --input '{"name": "World"}'
+```
+
+---
+
+## deepagents integration
+
+`pip install "path/to/pal/packages/sdk-python[deepagents]"` adds a
+[deepagents](https://github.com/langchain-ai/deepagents) sandbox backend that runs
+the agent's shell and filesystem inside a PAL microVM instead of on the host.
+Egress allowlist, secret vending, and per-tenant quota are enforced by the runtime,
+not by the prompt — untrusted agent code never touches a bare shell (invariant #5).
+
+```python
+from deepagents import create_deep_agent
+from pal.integrations.deepagents_sandbox import PalSandbox
+
+with PalSandbox.create(image_digest="sha256:...") as sandbox:
+    agent = create_deep_agent(backend=sandbox)
+    agent.invoke({"messages": [{"role": "user", "content": "run the tests"}]})
+```
+
+`PalSandbox` implements deepagents' `SandboxBackendProtocol`. deepagents'
+`BaseSandbox` derives the full filesystem toolset (`ls`/`read`/`write`/`edit`/
+`glob`/`grep`) from three primitives, so the backend is just those three mapped
+onto the runtime REST surface:
+
+| Backend method                   | PAL endpoint                          |
+| -------------------------------- | ----------------------------------------- |
+| `execute()`                      | `POST /v1/runtime/vms/{id}/exec`          |
+| `upload_files()`/`download_files()` | base64 over the same exec channel      |
+| `create()` / `close()`           | `POST /v1/runtime/schedule` / `DELETE /v1/runtime/vms/{id}` |
+
+Constructors:
+
+- `PalSandbox.create(image_digest=..., **spec)` — schedules a fresh microVM and
+  polls until it is `running`. Extra kwargs pass through to `/v1/runtime/schedule`
+  (`limits`, `egressRules`, `secrets`, `labels`, ...). Terminates the VM on exit.
+- `PalSandbox.connect(vm_id)` — attaches to an already-running VM; does **not**
+  terminate it on close.
+
+Composes with deepagents' own `CompositeBackend` so state can outlive the VM —
+mount a store at `/memories/` while everything else executes in the sandbox. See
+[`examples/deepagents_sandbox_agent.py`](examples/deepagents_sandbox_agent.py) for a
+runnable version that also wires `RubricMiddleware` for in-loop self-evaluation.
+
+Reads `PAL_API_URL` / `PAL_API_KEY` like the main client; pass `base_url` /
+`api_key` explicitly to override.
+
+`create()` defaults the entrypoint to `sleep infinity`. A sandbox is a long-lived
+exec target, so an image whose own entrypoint runs to completion (`python:3.11-slim`
+just starts a REPL and exits) would be reaped by the runtime before the agent could
+exec into it. Pass an explicit `command` to override.
+
+**Verified against a real VM.** The full path — `PalSandbox` → control-plane
+→ runtime-scheduler → runtime-manager → real container — is exercised end to end
+on the `docker` backend, covering `execute`, binary upload/download roundtrip, and
+the BaseSandbox-derived `write`/`read`/`ls`/`edit`/`grep` the agent actually calls.
+The Go-side regression test is
+`services/control-plane/internal/handlers/runtime_exec_e2e_test.go` (opt-in via
+`PAL_RUNTIME_E2E=1`). The **Firecracker** path specifically is not verifiable
+on macOS (no `/dev/kvm`) — that is covered by the `microvm · integration` CI job on
+a KVM runner. Exec routing differs between them: the manager sends Firecracker VMs
+to the in-guest harness and everything else through the backend.
+
+**Known ceilings.** File transfer is base64-inline over the exec channel — fine for
+agent-sized files, but a large binary should move via object storage. A microVM
+image digest is required; the sandbox does not build one for you.
+
+---
+
+## Parity note
+
+The Python SDK's management surface (`agents`, `runs`, `sessions`, `connectors`,
+`budgets`, `evals`, `experiments`, `marketplace`, `mcp`, `receipts`, `feedback`,
+`rehearsals`, plus `debug` and `support`) is at parity with the TypeScript SDK's HTTP surface — all typed,
+none require raw `client._request(...)` calls. The agent definition layer
+(`@agent`, `step`, `tool`) mirrors the TypeScript surface except that `zod`
+schema validation is replaced by plain Python type hints and pydantic models.