pyflue 0.1.0__py3-none-any.whl

pyflue/__init__.py

@@ -0,0 +1,14 @@
+"""PyFlue public API."""
+
+from pyflue.core import PyFlueAgent, PyFlueSession, init
+from pyflue.harnesses.registry import register_harness
+from pyflue.skills import Skill, load_skills
+
+__all__ = [
+    "PyFlueAgent",
+    "PyFlueSession",
+    "Skill",
+    "init",
+    "load_skills",
+    "register_harness",
+]

pyflue/cli.py

@@ -0,0 +1,259 @@
+"""PyFlue command-line interface."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from pathlib import Path
+from typing import Any, Literal
+
+import typer
+from rich.console import Console
+
+from pyflue import init
+
+app = typer.Typer(help="PyFlue agent harness CLI.")
+skill_app = typer.Typer(help="Manage Markdown skills.")
+app.add_typer(skill_app, name="skill")
+console = Console()
+PROMPT_OPTION = typer.Option(..., "--prompt", "-p", help="Prompt to run.")
+SESSION_OPTION = typer.Option("default", "--session", "-s")
+CONFIG_OPTION = typer.Option("pyflue.toml", "--config")
+ALLOW_WRITE_OPTION = typer.Option(False, "--allow-write")
+ALLOW_SHELL_OPTION = typer.Option(False, "--allow-shell")
+PORT_OPTION = typer.Option(2024, "--port")
+PROJECT_NAME_ARGUMENT = typer.Argument("pyflue-agent")
+SKILL_NAME_ARGUMENT = typer.Argument(...)
+BuildTarget = Literal[
+    "docker",
+    "github-actions",
+    "gitlab-ci",
+    "railway",
+    "render",
+    "fly",
+]
+
+
+@app.command("init")
+def init_project(name: str = PROJECT_NAME_ARGUMENT, force: bool = False) -> None:
+    """Scaffold a PyFlue project."""
+    root = Path(name).resolve()
+    if root.exists() and any(root.iterdir()) and not force:
+        raise typer.BadParameter(f"{root} is not empty. Use --force to overwrite.")
+    (root / ".agents" / "skills").mkdir(parents=True, exist_ok=True)
+    (root / "AGENTS.md").write_text(
+        "You are a careful autonomous Python agent. Keep changes scoped.\n",
+        encoding="utf-8",
+    )
+    (root / "pyflue.toml").write_text(
+        '[agent]\nmodel = "openai:gpt-4o"\nharness = "deepagents"\nsandbox = "virtual"\n',
+        encoding="utf-8",
+    )
+    _write_skill(root / ".agents" / "skills" / "triage.md", "triage")
+    console.print(f"Created PyFlue project at {root}")
+
+
+@app.command()
+def run(
+    prompt: str = PROMPT_OPTION,
+    session: str = SESSION_OPTION,
+    config: Path = CONFIG_OPTION,
+    allow_write: bool = ALLOW_WRITE_OPTION,
+    allow_shell: bool = ALLOW_SHELL_OPTION,
+) -> None:
+    """Run one PyFlue prompt."""
+
+    async def _run() -> None:
+        agent = await init(
+            config_path=config,
+            allow_write=allow_write,
+            allow_shell=allow_shell,
+        )
+        result = await (await agent.session(session)).prompt(prompt)
+        console.print(result.text)
+
+    asyncio.run(_run())
+
+
+@app.command()
+def dev(port: int = PORT_OPTION, config: Path = CONFIG_OPTION) -> None:
+    """Start a development server with hot-reload support."""
+    console.print(
+        f"pyflue dev is planned for FastAPI hot reload. Config={config}, port={port}"
+    )
+
+
+@app.command()
+def build(target: BuildTarget = "docker") -> None:
+    """Generate deployment artifacts."""
+    if target == "docker":
+        _write_docker_artifacts()
+        console.print("Generated Dockerfile and app.py")
+    elif target == "github-actions":
+        _write_github_actions_workflow()
+        console.print("Generated .github/workflows/pyflue-agent.yml")
+    elif target == "gitlab-ci":
+        _write_gitlab_ci()
+        console.print("Generated .gitlab-ci.yml")
+    elif target == "railway":
+        _write_docker_artifacts()
+        Path("railway.json").write_text(
+            '{\n  "$schema": "https://railway.app/railway.schema.json",\n'
+            '  "build": {"builder": "DOCKERFILE"},\n'
+            '  "deploy": {"startCommand": "uvicorn app:app --host 0.0.0.0 --port $PORT"}\n'
+            "}\n",
+            encoding="utf-8",
+        )
+        console.print("Generated Dockerfile, app.py, and railway.json")
+    elif target == "render":
+        _write_docker_artifacts()
+        Path("render.yaml").write_text(
+            "services:\n"
+            "  - type: web\n"
+            "    name: pyflue-agent\n"
+            "    runtime: docker\n"
+            "    plan: starter\n"
+            "    envVars:\n"
+            "      - key: PORT\n"
+            "        value: 8000\n",
+            encoding="utf-8",
+        )
+        console.print("Generated Dockerfile, app.py, and render.yaml")
+    elif target == "fly":
+        _write_docker_artifacts()
+        Path("fly.toml").write_text(
+            'app = "pyflue-agent"\n'
+            'primary_region = "iad"\n\n'
+            "[http_service]\n"
+            "  internal_port = 8000\n"
+            "  force_https = true\n"
+            "  auto_stop_machines = true\n"
+            "  auto_start_machines = true\n",
+            encoding="utf-8",
+        )
+        console.print("Generated Dockerfile, app.py, and fly.toml")
+
+
+@app.command()
+def deploy(dry_run: bool = False) -> None:
+    """Deploy the PyFlue agent using the configured harness."""
+    console.print("Dry run: deployment config is valid." if dry_run else "pyflue deploy is planned.")
+
+
+@skill_app.command("new")
+def new_skill(name: str = SKILL_NAME_ARGUMENT) -> None:
+    """Create a new Markdown skill."""
+    path = Path(".agents") / "skills" / f"{name}.md"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    _write_skill(path, name)
+    console.print(f"Created skill {path}")
+
+
+def _write_skill(path: Path, name: str) -> None:
+    content = {
+        "name": name,
+        "description": f"{name} workflow",
+        "input_schema": {"type": "object", "properties": {}},
+        "output_schema": {"type": "object", "properties": {"summary": {"type": "string"}}},
+    }
+    frontmatter = "\n".join(
+        [
+            "---",
+            f"name: {content['name']}",
+            f"description: {content['description']}",
+            "input_schema:",
+            "  type: object",
+            "  properties: {}",
+            "output_schema:",
+            "  type: object",
+            "  properties:",
+            "    summary:",
+            "      type: string",
+            "---",
+            "",
+            "# Role",
+            "You are a PyFlue skill.",
+            "",
+            "## Instructions",
+            "Complete the requested workflow and return a concise result.",
+        ]
+    )
+    path.write_text(frontmatter, encoding="utf-8")
+
+
+def _write_docker_artifacts() -> None:
+    Path("Dockerfile").write_text(
+        "FROM python:3.11-slim\n"
+        "WORKDIR /app\n"
+        "COPY . .\n"
+        "RUN pip install . fastapi uvicorn\n"
+        'CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]\n',
+        encoding="utf-8",
+    )
+    Path("app.py").write_text(
+        "from fastapi import FastAPI\n"
+        "from pydantic import BaseModel\n\n"
+        "from pyflue import init\n\n\n"
+        "class PromptRequest(BaseModel):\n"
+        "    prompt: str\n"
+        "    session: str = \"default\"\n\n\n"
+        "app = FastAPI(title=\"PyFlue Agent\")\n\n\n"
+        "@app.post(\"/prompt\")\n"
+        "async def prompt(request: PromptRequest):\n"
+        "    agent = await init()\n"
+        "    session = await agent.session(request.session)\n"
+        "    result = await session.prompt(request.prompt)\n"
+        "    return {\"text\": result.text, \"metadata\": result.metadata}\n",
+        encoding="utf-8",
+    )
+
+
+def _write_github_actions_workflow() -> None:
+    path = Path(".github") / "workflows" / "pyflue-agent.yml"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        "name: PyFlue Agent\n\n"
+        "on:\n"
+        "  workflow_dispatch:\n"
+        "    inputs:\n"
+        "      prompt:\n"
+        "        description: Prompt to run\n"
+        "        required: true\n"
+        "        default: Review this repository\n\n"
+        "jobs:\n"
+        "  agent:\n"
+        "    runs-on: ubuntu-latest\n"
+        "    permissions:\n"
+        "      contents: read\n"
+        "    steps:\n"
+        "      - uses: actions/checkout@v4\n"
+        "      - uses: astral-sh/setup-uv@v5\n"
+        "      - uses: actions/setup-python@v5\n"
+        "        with:\n"
+        "          python-version: '3.12'\n"
+        "      - run: uv sync\n"
+        "      - name: Run PyFlue agent\n"
+        "        env:\n"
+        "          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}\n"
+        "        run: uv run pyflue run --allow-shell --prompt \"${{ inputs.prompt }}\"\n",
+        encoding="utf-8",
+    )
+
+
+def _write_gitlab_ci() -> None:
+    Path(".gitlab-ci.yml").write_text(
+        "pyflue-agent:\n"
+        "  image: ghcr.io/astral-sh/uv:python3.12-bookworm-slim\n"
+        "  rules:\n"
+        "    - if: $CI_PIPELINE_SOURCE == \"web\"\n"
+        "  variables:\n"
+        "    PROMPT: \"Review this repository\"\n"
+        "  script:\n"
+        "    - uv sync\n"
+        "    - uv run pyflue run --allow-shell --prompt \"$PROMPT\"\n",
+        encoding="utf-8",
+    )
+
+
+def _parse_payload(payload: str | None) -> dict[str, Any]:
+    return json.loads(payload or "{}")

pyflue/config.py

@@ -0,0 +1,38 @@
+"""pyflue.toml loading."""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+from typing import Any
+
+from pyflue.types import PyFlueConfig
+
+
+def load_config(path: str | Path = "pyflue.toml") -> PyFlueConfig:
+    """Load PyFlue configuration from TOML."""
+    config_path = Path(path).expanduser()
+    root = config_path.parent.resolve() if config_path.exists() else Path.cwd()
+    data: dict[str, Any] = {}
+    if config_path.exists():
+        data = tomllib.loads(config_path.read_text(encoding="utf-8"))
+
+    agent = data.get("agent", {}) if isinstance(data.get("agent"), dict) else {}
+    harness = str(agent.get("harness", "deepagents") or "deepagents")
+    sandbox = str(agent.get("sandbox", "virtual") or "virtual")
+    skills_dir = agent.get("skills_dir")
+    state_dir = agent.get("state_dir")
+
+    return PyFlueConfig(
+        model=agent.get("model"),
+        harness=harness,
+        sandbox=sandbox,
+        root=root,
+        skills_dir=(root / skills_dir).resolve() if skills_dir else None,
+        state_dir=(root / state_dir).resolve() if state_dir else None,
+        harness_config={
+            key: value
+            for key, value in data.items()
+            if key not in {"agent", "deployment"}
+        },
+    )

pyflue/core.py

@@ -0,0 +1,216 @@
+"""PyFlue core agent and session API."""
+
+from __future__ import annotations
+
+import json
+import re
+import uuid
+from pathlib import Path
+from typing import Any
+
+import aiosqlite
+from pydantic import BaseModel, TypeAdapter
+
+from pyflue.config import load_config
+from pyflue.harnesses.registry import create_backend
+from pyflue.sandbox import SandboxPolicy, VirtualSandbox
+from pyflue.skills import load_project_instructions, load_skills, render_skill_prompt
+from pyflue.types import HarnessResult, PyFlueConfig
+
+RESULT_START = "---RESULT_START---"
+RESULT_END = "---RESULT_END---"
+_RESULT_RE = re.compile(
+    rf"{RESULT_START}\s*\n(?P<body>[\s\S]*?)\n?{RESULT_END}",
+    re.MULTILINE,
+)
+
+
+async def init(
+    *,
+    model: str | None = None,
+    harness: str | None = None,
+    sandbox: str | None = None,
+    skills_dir: str | Path | None = None,
+    config_path: str | Path | None = None,
+    env: dict[str, str] | None = None,
+    allow_write: bool = False,
+    allow_shell: bool = False,
+) -> PyFlueAgent:
+    """Initialize a PyFlue agent."""
+    config = load_config(config_path or "pyflue.toml")
+    if model is not None:
+        config.model = model
+    if harness is not None:
+        config.harness = harness
+    if sandbox is not None:
+        config.sandbox = sandbox
+    if skills_dir is not None:
+        path = Path(skills_dir).expanduser()
+        config.skills_dir = path if path.is_absolute() else config.root / path
+    if env:
+        config.env.update({str(key): str(value) for key, value in env.items()})
+    return PyFlueAgent(
+        config=config,
+        sandbox_policy=SandboxPolicy(allow_write=allow_write, allow_shell=allow_shell),
+    )
+
+
+class PyFlueAgent:
+    """Factory for stateful PyFlue sessions."""
+
+    def __init__(
+        self,
+        *,
+        config: PyFlueConfig,
+        sandbox_policy: SandboxPolicy | None = None,
+    ):
+        self.config = config
+        self.backend = create_backend(config.harness)
+        self.instructions = load_project_instructions(config.root)
+        self.skills = load_skills(config.root, config.skills_dir)
+        self.sandbox = VirtualSandbox(config.root, policy=sandbox_policy)
+        self.state_dir = config.state_dir or config.root / ".pyflue" / "sessions"
+        self.state_dir.mkdir(parents=True, exist_ok=True)
+
+    async def session(self, session_id: str | None = None) -> PyFlueSession:
+        """Open or create a persistent session."""
+        sid = session_id or "default"
+        session = PyFlueSession(agent=self, session_id=sid)
+        await session._ensure_store()
+        return session
+
+
+class PyFlueSession:
+    """One persistent PyFlue conversation."""
+
+    def __init__(self, *, agent: PyFlueAgent, session_id: str):
+        self.agent = agent
+        self.session_id = session_id
+        safe_id = re.sub(r"[^a-zA-Z0-9_.-]+", "_", session_id)
+        self.db_path = self.agent.state_dir / f"{safe_id}.sqlite3"
+
+    async def prompt(
+        self,
+        text: str,
+        *,
+        result: type[BaseModel] | Any | None = None,
+    ) -> HarnessResult | Any:
+        """Run one prompt turn."""
+        prompt = self._build_prompt(text, result=result)
+        await self._append("user", text)
+        history = await self._history_prompt(prompt)
+        output = await self.agent.backend.run(
+            prompt=history,
+            system_prompt=self.agent.instructions,
+            config=self.agent.config,
+            skills=self.agent.skills,
+            sandbox=self.agent.sandbox,
+            session_id=self.session_id,
+        )
+        await self._append("assistant", output.text)
+        if result is not None:
+            return _parse_typed_result(output.text, result)
+        return output
+
+    async def skill(
+        self,
+        name: str,
+        *,
+        args: dict[str, Any] | None = None,
+        result: type[BaseModel] | Any | None = None,
+    ) -> HarnessResult | Any:
+        """Run a Markdown-defined skill."""
+        skill = self.agent.skills.get(name)
+        if skill is None:
+            available = ", ".join(sorted(self.agent.skills)) or "(none)"
+            raise KeyError(f"Unknown skill '{name}'. Available skills: {available}")
+        prompt = render_skill_prompt(skill, args=args)
+        return await self.prompt(prompt, result=result)
+
+    async def subagent(
+        self,
+        prompt: str,
+        *,
+        result: type[BaseModel] | Any | None = None,
+    ) -> HarnessResult | Any:
+        """Run a child session with isolated history and shared sandbox."""
+        child_id = f"{self.session_id}:task:{uuid.uuid4().hex[:10]}"
+        child = await self.agent.session(child_id)
+        output = await child.prompt(prompt, result=result)
+        await self._append("assistant", f"Subagent {child_id} completed.")
+        return output
+
+    async def shell(self, command: str, *, timeout: int | None = 120) -> dict[str, Any]:
+        """Run a shell command through the configured sandbox."""
+        output = await self.agent.backend.shell(
+            command,
+            sandbox=self.agent.sandbox,
+            timeout=timeout,
+        )
+        await self._append("tool", json.dumps(output, sort_keys=True))
+        return output
+
+    async def read_file(self, path: str) -> str:
+        """Read a file from the session sandbox."""
+        return self.agent.sandbox.read_file(path)
+
+    async def write_file(self, path: str, content: str) -> str:
+        """Write a file into the session sandbox."""
+        return self.agent.sandbox.write_file(path, content)
+
+    async def _ensure_store(self) -> None:
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.execute(
+                "create table if not exists messages "
+                "(id integer primary key autoincrement, role text not null, content text not null)"
+            )
+            await db.commit()
+
+    async def _append(self, role: str, content: str) -> None:
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.execute(
+                "insert into messages(role, content) values (?, ?)",
+                (role, content),
+            )
+            await db.commit()
+
+    async def _messages(self) -> list[tuple[str, str]]:
+        async with aiosqlite.connect(self.db_path) as db:
+            cursor = await db.execute(
+                "select role, content from messages order by id desc limit 12"
+            )
+            rows = await cursor.fetchall()
+        return list(reversed([(str(role), str(content)) for role, content in rows]))
+
+    async def _history_prompt(self, prompt: str) -> str:
+        rows = await self._messages()
+        if not rows:
+            return prompt
+        history = "\n\n".join(f"{role}: {content}" for role, content in rows)
+        return f"Conversation so far:\n{history}\n\nNext:\n{prompt}"
+
+    def _build_prompt(self, text: str, *, result: Any | None = None) -> str:
+        parts = [
+            "You are running inside PyFlue, a headless Python agent harness.",
+            text.strip(),
+        ]
+        if result is not None:
+            schema = TypeAdapter(result).json_schema()
+            parts.extend(
+                [
+                    "Return the final structured result between these exact delimiters:",
+                    RESULT_START,
+                    json.dumps(schema, indent=2, sort_keys=True),
+                    RESULT_END,
+                ]
+            )
+        return "\n\n".join(parts)
+
+
+def _parse_typed_result(text: str, result: Any) -> Any:
+    matches = list(_RESULT_RE.finditer(text or ""))
+    raw = matches[-1].group("body").strip() if matches else text.strip()
+    value: Any = raw
+    if raw.startswith("{") or raw.startswith("["):
+        value = json.loads(raw)
+    return TypeAdapter(result).validate_python(value)

pyflue/harnesses/__init__.py

@@ -0,0 +1,6 @@
+"""PyFlue harness backends."""
+
+from pyflue.harnesses.base import HarnessBackend
+from pyflue.harnesses.registry import create_backend, register_harness
+
+__all__ = ["HarnessBackend", "create_backend", "register_harness"]

pyflue/harnesses/base.py

@@ -0,0 +1,31 @@
+"""Harness backend interface."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from pyflue.types import HarnessResult, PyFlueConfig, Skill
+
+
+class HarnessBackend(ABC):
+    """Backend contract implemented by all harness integrations."""
+
+    name: str
+
+    @abstractmethod
+    async def run(
+        self,
+        *,
+        prompt: str,
+        system_prompt: str,
+        config: PyFlueConfig,
+        skills: dict[str, Skill],
+        sandbox: Any,
+        session_id: str,
+    ) -> HarnessResult:
+        """Run one prompt turn."""
+
+    async def shell(self, command: str, *, sandbox: Any, timeout: int | None = None) -> dict[str, Any]:
+        """Run a shell command through the configured sandbox."""
+        return sandbox.shell(command, timeout=timeout)