pal-code 0.1.0__py3-none-any.whl

pal/sdk/components/autogen_adapter.py

@@ -0,0 +1,65 @@
+"""
+Adapter for AutoGen (Wu et al., 2023). AutoGen's ConversableAgent
+ultimately calls out to an OpenAIWrapper instance's .create() method,
+which builds the actual chat-completion request. This adapter
+monkeypatches OpenAIWrapper.create to call the AgentSDK's chat()
+instead, and wraps the reply back into the minimal ChatCompletion-like
+shape (.choices[0].message.content) AutoGen's own code reads from --
+so callers inside AutoGen don't notice the difference.
+
+Targets the AutoGen 0.2 API (`autogen.oai.client.OpenAIWrapper`, the `pyautogen<0.3` / `ag2<1` line). The
+redesigned AutoGen (autogen-agentchat 0.4+) has no such class; use `PalChatCompletionClient` for that one.
+Text replies only: tool and function calling are not redirected.
+"""
+from types import SimpleNamespace
+
+from pal.sdk.components.framework_adapter_base import FrameworkAdapter, FrameworkAdapterError
+
+
+class AutoGenAdapter(FrameworkAdapter):
+    framework_name = "autogen"
+
+    def install(self) -> None:
+        try:
+            from autogen.oai.client import OpenAIWrapper
+        except ImportError as e:
+            raise FrameworkAdapterError(
+                "AutoGen 0.2 is not installed -- run `pip install \"pyautogen==0.2.35\"` to use this adapter. For AutoGen 0.4+ "
+                "use pal.sdk.autogen_model_client(sdk) instead"
+            ) from e
+
+        if not hasattr(OpenAIWrapper, "create"):
+            raise FrameworkAdapterError(
+                "autogen.oai.client.OpenAIWrapper has no 'create' method -- this adapter "
+                "targets the AutoGen API this project was built against; a newer or older "
+                "AutoGen version may have changed it"
+            )
+
+        self._check_free(OpenAIWrapper.create)
+        self._target = OpenAIWrapper
+        self._original = OpenAIWrapper.create
+        sdk = self.sdk
+
+        def _redirected_create(self_wrapper, **kwargs):
+            messages = kwargs.get("messages", [])
+            call = {k: kwargs[k] for k in ("max_tokens", "temperature") if isinstance(kwargs.get(k), (int, float))}
+            if "max_tokens" in call:
+                call["max_tokens"] = int(call["max_tokens"])
+            resp = sdk.chat_response(messages, **call)
+            message = SimpleNamespace(content=resp.text, role="assistant", function_call=None, tool_calls=None)
+            choice = SimpleNamespace(message=message, finish_reason="stop", index=0)
+            usage = SimpleNamespace(prompt_tokens=resp.prompt_tokens, completion_tokens=resp.completion_tokens,
+                                    total_tokens=resp.prompt_tokens + resp.completion_tokens)
+            # AutoGen 0.2 reads these back from every response (extract_text_or_completion_object, usage, cost)
+            return SimpleNamespace(
+                choices=[choice], model=kwargs.get("model", "pal-code"), usage=usage, cost=0.0, config_id=0,
+                pass_filter=None,
+                message_retrieval_function=lambda r: [c.message.content for c in r.choices])
+
+        OpenAIWrapper.create = self._mark(_redirected_create)
+        self._installed = True
+
+    def uninstall(self) -> None:
+        if self._installed:
+            self._target.create = self._original
+            self._installed = False

pal/sdk/components/autogen_client.py

@@ -0,0 +1,98 @@
+"""Pal-backed model client for the current AutoGen (autogen-agentchat 0.4 and later).
+
+The redesigned AutoGen takes a `model_client=` object instead of calling a patchable class, so no monkeypatching
+is needed: pass this client to any AutoGen agent and every model call goes through the Pal SDK.
+
+    sdk = AgentSDK.standalone(WrapperConfig(backend="gemini", model="...", api_key="..."))
+    agent = AssistantAgent("helper", model_client=autogen_model_client(sdk))
+
+Text only: AutoGen's tool and function calling are not redirected (a clear error is raised if requested).
+"""
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Sequence
+from typing import Any
+
+from pal.sdk.components.framework_adapter_base import FrameworkAdapterError
+from pal.tokens import estimate_tokens
+
+
+def autogen_model_client(sdk, model: str = "pal-code") -> Any:
+    try:
+        from autogen_core.models import (
+            AssistantMessage,
+            ChatCompletionClient,
+            CreateResult,
+            ModelInfo,
+            RequestUsage,
+            SystemMessage,
+        )
+    except ImportError as e:
+        raise FrameworkAdapterError(
+            "autogen-agentchat is not installed -- run `pip install autogen-agentchat` (AutoGen 0.4+) to use this client"
+        ) from e
+
+    def to_text(content: Any) -> str:
+        return content if isinstance(content, str) else " ".join(str(getattr(p, "content", p)) for p in content)
+
+    def convert(messages: Sequence[Any]) -> list[dict]:
+        out = []
+        for m in messages:
+            role = "system" if isinstance(m, SystemMessage) else "assistant" if isinstance(m, AssistantMessage) else "user"
+            out.append({"role": role, "content": to_text(getattr(m, "content", ""))})
+        return out
+
+    class PalChatCompletionClient(ChatCompletionClient):
+        def __init__(self) -> None:
+            self._sdk = sdk
+            self._total = RequestUsage(prompt_tokens=0, completion_tokens=0)
+            self._last = RequestUsage(prompt_tokens=0, completion_tokens=0)
+
+        async def create(self, messages, *, tools=(), tool_choice="auto", json_output=None, extra_create_args=None,
+                         cancellation_token=None):
+            if tools:
+                raise FrameworkAdapterError("tool calling is not supported through the Pal model client")
+            args = dict(extra_create_args or {})
+            call = {k: args[k] for k in ("max_tokens", "temperature") if isinstance(args.get(k), (int, float))}
+            if "max_tokens" in call:
+                call["max_tokens"] = int(call["max_tokens"])
+            resp = await asyncio.to_thread(self._sdk.chat_response, convert(messages), **call)  # never block the loop
+            self._last = RequestUsage(prompt_tokens=resp.prompt_tokens or 0, completion_tokens=resp.completion_tokens or 0)
+            self._total = RequestUsage(prompt_tokens=self._total.prompt_tokens + self._last.prompt_tokens,
+                                       completion_tokens=self._total.completion_tokens + self._last.completion_tokens)
+            return CreateResult(finish_reason="stop", content=resp.text, usage=self._last,
+                                cached=bool(resp.meta.get("cache")))
+
+        async def create_stream(self, messages, *, tools=(), tool_choice="auto", json_output=None,
+                                extra_create_args=None, cancellation_token=None):
+            result = await self.create(messages, tools=tools, tool_choice=tool_choice, json_output=json_output,
+                                       extra_create_args=extra_create_args, cancellation_token=cancellation_token)
+            yield str(result.content)
+            yield result
+
+        async def close(self) -> None:
+            return None
+
+        def actual_usage(self):
+            return self._total
+
+        def total_usage(self):
+            return self._total
+
+        def count_tokens(self, messages, *, tools=()) -> int:
+            return sum(estimate_tokens(m["content"]) for m in convert(messages))
+
+        def remaining_tokens(self, messages, *, tools=()) -> int:
+            return max(0, 100_000 - self.count_tokens(messages))
+
+        @property
+        def capabilities(self):
+            return self.model_info
+
+        @property
+        def model_info(self):
+            return ModelInfo(vision=False, function_calling=False, json_output=False, family=model,
+                             structured_output=False)
+
+    return PalChatCompletionClient()

pal/sdk/components/framework_adapter_base.py

@@ -0,0 +1,69 @@
+"""
+Agent framework adapters (AIOS section 3.9): let agents built with an
+existing framework (Autogen, Open Interpreter, MetaGPT, ...) run inside
+pal without any modification to the agent's own code. Each
+adapter locates that framework's core LLM-completion function and
+monkeypatches it to redirect through an AgentSDK's chat() instead -- so
+the framework keeps its own agent-creation API, but every actual model
+call goes through pal's llm_wrapper (compression, caching, paging,
+the syscall scheduler, all of it) rather than the framework's own HTTP
+client.
+
+These adapters target each framework's documented core completion
+entry point. A framework's internals can and do change between
+releases, so install() raises a clear FrameworkAdapterError (naming the
+missing attribute) rather than failing silently if a targeted attribute
+path isn't found -- an adapter that silently no-ops would leave an
+agent quietly calling the real API instead of pal, which is worse
+than a loud failure that tells the caller exactly what broke.
+"""
+from abc import ABC, abstractmethod
+
+from pal.sdk.pipeline import AgentSDK
+
+
+class FrameworkAdapterError(RuntimeError):
+    pass
+
+
+class FrameworkAdapter(ABC):
+    framework_name: str = "base"
+
+    def __init__(self, sdk: AgentSDK):
+        self.sdk = sdk
+        self._installed = False
+
+    @abstractmethod
+    def install(self) -> None:
+        """Monkeypatches the framework's core completion function to
+        redirect through self.sdk.chat(). Raises FrameworkAdapterError
+        if the framework isn't installed, or if its expected entry
+        point isn't found (version mismatch)."""
+        ...
+
+    @abstractmethod
+    def uninstall(self) -> None:
+        """Restores the framework's original completion function."""
+        ...
+
+    @property
+    def installed(self) -> bool:
+        return self._installed
+
+    @staticmethod
+    def _check_free(fn) -> None:
+        """Refuse to patch a function another adapter already replaced: two SDKs cannot share one framework."""
+        if getattr(fn, "_pal_adapter", False):
+            raise FrameworkAdapterError("this framework is already adapted by another SDK; uninstall that one first")
+
+    @staticmethod
+    def _mark(fn):
+        fn._pal_adapter = True
+        return fn
+
+    def __enter__(self):
+        self.install()
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.uninstall()

pal/sdk/components/metagpt_adapter.py

@@ -0,0 +1,46 @@
+"""
+Adapter for MetaGPT (Hong et al., 2023). Every MetaGPT LLM provider
+(OpenAILLM, etc.) subclasses BaseLLM and implements `acompletion_text`
+as the actual async call to the model. This adapter monkeypatches
+BaseLLM.acompletion_text so MetaGPT's roles/actions keep working
+unmodified while the underlying call routes through pal.
+"""
+import asyncio
+
+from pal.sdk.components.framework_adapter_base import FrameworkAdapter, FrameworkAdapterError
+
+
+class MetaGPTAdapter(FrameworkAdapter):
+    framework_name = "metagpt"
+
+    def install(self) -> None:
+        try:
+            from metagpt.provider.base_llm import BaseLLM
+        except ImportError as e:
+            raise FrameworkAdapterError(
+                "metagpt is not installed -- run `pip install metagpt` to use this adapter"
+            ) from e
+
+        if not hasattr(BaseLLM, "acompletion_text"):
+            raise FrameworkAdapterError(
+                "metagpt.provider.base_llm.BaseLLM has no 'acompletion_text' method -- this "
+                "adapter targets the MetaGPT API this project was built against; a newer or "
+                "older version may have changed it"
+            )
+
+        self._check_free(BaseLLM.acompletion_text)
+        self._target = BaseLLM
+        self._original = BaseLLM.acompletion_text
+        sdk = self.sdk
+
+        async def _redirected_acompletion_text(self_llm, messages, stream=False, timeout=None):
+            # the SDK call is synchronous: run it in a thread so MetaGPT's event loop is never blocked
+            return await asyncio.to_thread(sdk.chat, messages)
+
+        BaseLLM.acompletion_text = self._mark(_redirected_acompletion_text)
+        self._installed = True
+
+    def uninstall(self) -> None:
+        if self._installed:
+            self._target.acompletion_text = self._original
+            self._installed = False

pal/sdk/components/open_interpreter_adapter.py

@@ -0,0 +1,47 @@
+"""
+Adapter for Open Interpreter (Lucas, 2024). Open Interpreter's core
+completion call runs through its `interpreter.llm` object's
+`completions` generator (normally built on top of litellm). This
+adapter monkeypatches that object's `completions` attribute so the
+AgentSDK is what actually produces tokens, while Open Interpreter's own
+tool-execution loop keeps running unmodified.
+"""
+from pal.sdk.components.framework_adapter_base import FrameworkAdapter, FrameworkAdapterError
+
+
+class OpenInterpreterAdapter(FrameworkAdapter):
+    framework_name = "open_interpreter"
+
+    def install(self) -> None:
+        try:
+            import interpreter as oi
+        except ImportError as e:
+            raise FrameworkAdapterError(
+                "open-interpreter is not installed -- run `pip install open-interpreter` to use this adapter"
+            ) from e
+
+        llm = getattr(oi.interpreter, "llm", None)
+        if llm is None:
+            raise FrameworkAdapterError(
+                "interpreter.interpreter.llm was not found -- this adapter targets the "
+                "Open Interpreter API this project was built against; a newer or older "
+                "version may have changed it"
+            )
+
+        self._check_free(getattr(llm, "completions", None))
+        self._target = llm
+        self._original = getattr(llm, "completions", None)
+        sdk = self.sdk
+
+        def _redirected_completions(**kwargs):
+            messages = kwargs.get("messages", [])
+            text = sdk.chat(messages)
+            yield {"choices": [{"delta": {"content": text}}]}
+
+        llm.completions = self._mark(_redirected_completions)
+        self._installed = True
+
+    def uninstall(self) -> None:
+        if self._installed:
+            self._target.completions = self._original
+            self._installed = False

pal/sdk/components/tool_catalog.py

@@ -0,0 +1,44 @@
+"""
+A small built-in tool catalog (AIOS section 3.9's "Tool Integration"):
+a minimal, dependency-free set of example tools covering a few
+different input/output modalities (free text, structured expressions,
+plain numbers), registered into a ToolManagerPipeline so a fresh
+AgentSDK has something callable out of the box.
+
+This is intentionally small. AIOS's own SDK ships a much larger
+catalog of tools sourced from real external platforms, which needs
+network access and API keys this project doesn't assume are available.
+Real deployments register their own tools alongside (or instead of)
+these via ToolManagerPipeline.register_tool() -- this catalog is a
+starting point, not a ceiling.
+"""
+import time
+
+from pal.tool_manager.builtin import safe_eval
+from pal.tool_manager.components.base import ToolParam
+from pal.tool_manager.pipeline import ToolManagerPipeline
+
+
+def _calculator():
+    # AST-based evaluator: never eval(), so it cannot execute code and cannot be made to hang.
+    return safe_eval
+
+
+def _current_time():
+    def current_time() -> str:
+        return time.strftime("%Y-%m-%d %H:%M:%S")
+
+    return current_time
+
+
+def _word_count():
+    def word_count(text: str) -> int:
+        return len(text.split())
+
+    return word_count
+
+
+def register_builtin_tools(tool_manager: ToolManagerPipeline) -> None:
+    tool_manager.register_tool("calculator", _calculator, params=[ToolParam("expression", str)])
+    tool_manager.register_tool("current_time", _current_time, params=[])
+    tool_manager.register_tool("word_count", _word_count, params=[ToolParam("text", str)])

pal/sdk/os_api.py

@@ -0,0 +1,84 @@
+"""`sdk.os`: friendly names for the OS-kernel queries. Each call is an OSQuery routed to the OS kernel; a refusal
+raises OSKernelError instead of returning an error value."""
+from __future__ import annotations
+
+from typing import Any
+
+from pal.os_kernel import OSKernelError
+from pal.sdk.queries import OSQuery
+
+
+class OSAPI:
+    def __init__(self, sdk: Any):
+        self._sdk = sdk
+
+    def _call(self, op: str, **params: Any) -> Any:
+        resp = self._sdk.send_request(OSQuery(op=op, params=params))
+        if not resp.ok:
+            raise OSKernelError(resp.error)
+        return resp.data
+
+    def read_file(self, path: str) -> str:
+        return self._call("file_read", path=path)
+
+    def write_file(self, path: str, content: str) -> dict:
+        return self._call("file_write", path=path, content=content)
+
+    def read_bytes(self, path: str) -> bytes:
+        """A workspace file as bytes (images, audio, PDFs, ...), within the OS kernel's binary size limit."""
+        import base64
+        return base64.b64decode(self._call("file_read_b64", path=path)["b64"])
+
+    def file_to_markdown(self, path: str) -> str:
+        """Convert a PDF, Word, PowerPoint, Excel, EPUB, HTML or LaTeX file in the workspace to markdown, save it under converted/,
+        and return a description with the beginning of the text."""
+        from pal.errors import PalError
+        from pal.input_converters.components.base import ConversionError
+        from pal.input_converters.workspace import convert_workspace_file, describe
+        try:
+            r = convert_workspace_file(path, read_bytes=self.read_bytes, write_text=lambda p, t: self.write_file(p, t),
+                                       exists=lambda p: p in self.list_files(p))
+        except ConversionError as e:
+            raise PalError(str(e)) from e
+        return describe(r)
+
+    def list_files(self, prefix: str = "") -> list[str]:
+        return self._call("file_list", prefix=prefix)
+
+    def delete_file(self, path: str) -> dict:
+        return self._call("file_delete", path=path)
+
+    def http_get(self, url: str) -> dict:
+        return self._call("net_get", url=url)
+
+    def http_post(self, url: str, json: Any = None) -> dict:
+        return self._call("net_post", url=url, json=json)
+
+    def system_info(self) -> dict:
+        return self._call("sys_info")
+
+    def keyboard(self, **kw: Any) -> Any:
+        return self._call("keyboard", **kw)
+
+    def mouse(self, **kw: Any) -> Any:
+        return self._call("mouse", **kw)
+
+
+def register_os_tools(sdk: Any) -> list[str]:
+    """Make the OS operations callable as tools (for ReAct and similar agents). The tools run as OSQuery calls, so they
+    reach the OS kernel and never a model. Not registered by default: the chat's tools stay read-only."""
+    from pal.tool_manager.components.base import ToolParam
+
+    tm = sdk._tool_manager
+    api = sdk.os
+    specs = [
+        ("read_file", lambda: api.read_file, [ToolParam("path", str)]),
+        ("write_file", lambda: api.write_file, [ToolParam("path", str), ToolParam("content", str)]),
+        ("list_files", lambda: api.list_files, [ToolParam("prefix", str, required=False, default="")]),
+        ("file_to_markdown", lambda: api.file_to_markdown, [ToolParam("path", str)]),
+        ("http_get", lambda: api.http_get, [ToolParam("url", str)]),
+        ("system_info", lambda: api.system_info, []),
+    ]
+    for name, loader, params in specs:
+        tm.register_tool(name, loader, params=params)
+    return [n for n, _, _ in specs]

pal/sdk/patterns.py

@@ -0,0 +1,129 @@
+"""ReAct and Reflexion as native agent patterns.
+
+Both are reasoning *patterns* (papers), not libraries with a single call to intercept, so Pal ships them as
+ready-made native agents built only on SDK calls. Subclass or configure them to make your own agent.
+"""
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from pal.sdk.agent import AgentResult, NativeAgent
+
+_FINAL = re.compile(r"Final Answer:\s*(.*)", re.S | re.I)
+_ACTION = re.compile(r"^\s*Action:\s*([A-Za-z_][\w.-]*)\s*(.*)$", re.M)
+_CUT = re.compile(r"\n\s*Observation:.*", re.S)
+
+REACT_FORMAT = (
+    "Solve the task step by step. In each reply write 'Thought: <short reasoning>' and then either "
+    "'Action: <tool_name> {\"arg\": value}' (JSON arguments) or 'Final Answer: <answer>'. After an Action you "
+    "will receive 'Observation: <result>'. Tools: {tools}.")
+
+
+@dataclass
+class ReActStep:
+    thought: str
+    tool: str
+    args: dict
+    observation: str
+
+
+class ReActAgent(NativeAgent):
+    """Reason, act, observe (Yao et al., 2023): the model alternates thoughts with tool calls until it answers."""
+
+    max_steps = 6
+    max_tokens = 512
+    tools: list[str] | None = None        # tool names to offer; None = every tool the SDK has
+
+    def run(self, task: str, attachments: list[dict] | None = None, session: str = "agent") -> AgentResult:
+        names = self.tools if self.tools is not None else self.sdk.list_tools()
+        role = self.spec.role + "\n" if self.spec else ""
+        transcript: list[dict] = [{"role": "system", "content": role + REACT_FORMAT.replace("{tools}", ", ".join(names) or "none")},
+                                  {"role": "user", "content": task}]
+        steps: list[ReActStep] = []
+        for _ in range(self.max_steps):
+            text = _CUT.sub("", self.sdk.chat(transcript, max_tokens=self.max_tokens) or "")   # ignore invented observations
+            final = _FINAL.search(text)
+            if final:
+                return AgentResult(final.group(1).strip(), steps=steps)
+            act = _ACTION.search(text)
+            if act is None:                       # no action and no marker: treat the reply as the answer
+                return AgentResult(text.strip(), steps=steps)
+            tool, rest = act.group(1), act.group(2).strip()
+            try:
+                args = json.loads(rest) if rest else {}
+                if not isinstance(args, dict):
+                    raise ValueError("arguments must be a JSON object")
+                observation = str(self.sdk.call_tool(tool, **args))
+            except Exception as e:  # noqa: BLE001  (a bad call becomes an observation the model can react to)
+                args, observation = {}, f"error: {e}"
+            thought = text.split("Action:")[0].replace("Thought:", "").strip()
+            steps.append(ReActStep(thought, tool, args, observation))
+            transcript += [{"role": "assistant", "content": text}, {"role": "user", "content": f"Observation: {observation}"}]
+        return AgentResult("", ok=False, steps=steps, error=f"no final answer after {self.max_steps} steps")
+
+
+@dataclass
+class Trial:
+    answer: str
+    ok: bool
+    feedback: str
+    reflection: str = ""
+
+
+Evaluator = Callable[[str, str], "bool | tuple[bool, str]"]
+
+
+class ReflexionAgent(NativeAgent):
+    """Try, evaluate, reflect, retry (Shinn et al., 2023).
+
+    The actor (any native agent; plain model call by default) answers. An evaluator (your function, or the model
+    judging itself) says pass or fail. On failure the model writes a short lesson, which is kept in memory and
+    shown to the next attempt.
+    """
+
+    max_trials = 3
+    max_tokens = 400
+
+    def __init__(self, sdk: Any = None, kernel: Any = None, actor: NativeAgent | None = None,
+                 evaluator: Evaluator | None = None):
+        super().__init__(sdk, kernel)
+        self.actor = actor
+        self.evaluator = evaluator
+
+    def _act(self, prompt: str) -> str:
+        if self.actor is not None:
+            return self.actor.run(prompt).answer
+        return self.sdk.chat([{"role": "user", "content": prompt}], max_tokens=self.max_tokens)
+
+    def _evaluate(self, task: str, answer: str) -> tuple[bool, str]:
+        if self.evaluator is not None:
+            r = self.evaluator(task, answer)
+            return (r, "") if isinstance(r, bool) else (bool(r[0]), str(r[1]))
+        verdict = self.sdk.chat([
+            {"role": "system", "content": "Judge whether the answer correctly and completely solves the task. "
+                                          "Reply 'PASS' or 'FAIL: <reason>'."},
+            {"role": "user", "content": f"Task: {task}\nAnswer: {answer}"}], max_tokens=80) or ""
+        return verdict.strip().upper().startswith("PASS"), verdict.strip()
+
+    def run(self, task: str, attachments: list[dict] | None = None, session: str = "agent") -> AgentResult:
+        lessons: list[str] = []
+        trials: list[Trial] = []
+        for _ in range(self.max_trials):
+            prompt = task if not lessons else task + "\n\nLessons from earlier attempts:\n- " + "\n- ".join(lessons)
+            answer = self._act(prompt)
+            ok, feedback = self._evaluate(task, answer)
+            trial = Trial(answer, ok, feedback)
+            trials.append(trial)
+            if ok:
+                return AgentResult(answer, steps=trials)
+            trial.reflection = (self.sdk.chat([
+                {"role": "system", "content": "In one or two sentences say what went wrong and what to do differently."},
+                {"role": "user", "content": f"Task: {task}\nAnswer: {answer}\nFeedback: {feedback}"}],
+                max_tokens=120) or "").strip()
+            lessons.append(trial.reflection)
+            self.sdk.remember(trial.reflection, tags=["reflexion"])
+        return AgentResult(trials[-1].answer, ok=False, steps=trials, error=f"not solved in {self.max_trials} trials")