kaiwen-agent 0.1.0a1__tar.gz

kaiwen_agent-0.1.0a1/.gitignore

@@ -0,0 +1,17 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+*.py[cod]
+dist/
+build/
+*.egg-info/
+node_modules/
+coverage/
+.env
+.env.*
+!.env.example
+*.sqlite3
+*.sqlite3-shm
+*.sqlite3-wal

kaiwen_agent-0.1.0a1/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: kaiwen-agent
+Version: 0.1.0a1
+Summary: Provider-neutral asynchronous agent runtime
+Project-URL: Homepage, https://github.com/ImtheKaiwen/kaiwen-agent-platform
+Project-URL: Documentation, https://github.com/ImtheKaiwen/kaiwen-agent-platform/tree/main/docs
+Project-URL: Repository, https://github.com/ImtheKaiwen/kaiwen-agent-platform.git
+Project-URL: Issues, https://github.com/ImtheKaiwen/kaiwen-agent-platform/issues
+Author: Kaiwen
+License: MIT
+Keywords: agent,ai,asyncio,openai,tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pydantic<3,>=2.10
+Provides-Extra: dev
+Requires-Dist: mypy<2,>=1.14; extra == 'dev'
+Requires-Dist: openai<3,>=2; extra == 'dev'
+Requires-Dist: pytest<9,>=8.3; extra == 'dev'
+Requires-Dist: python-dotenv<2,>=1.1; extra == 'dev'
+Requires-Dist: ruff<1,>=0.9; extra == 'dev'
+Provides-Extra: openai
+Requires-Dist: openai<3,>=2; extra == 'openai'
+Provides-Extra: release
+Requires-Dist: build<2,>=1.2; extra == 'release'
+Requires-Dist: twine<7,>=6; extra == 'release'
+Description-Content-Type: text/markdown
+
+# kaiwen-agent
+
+Provider-neutral, asynchronous Python runtime for building tool-using agents.
+Product applications own their prompts, domain tools, authorization context,
+persistence choice, and HTTP surface.
+
+```bash
+pip install "kaiwen-agent[openai]"
+```
+
+## Minimal agent
+
+```python
+import asyncio
+
+from pydantic import BaseModel
+
+from kaiwen_agent import Agent, AgentContext, tool
+from kaiwen_agent.models.openai import OpenAIResponsesProvider
+from kaiwen_agent.types import AgentInput
+
+
+class ProjectQuery(BaseModel):
+    category: str | None = None
+
+
+@tool(
+    name="projects.read",
+    description="List projects visible to the current user",
+    input_model=ProjectQuery,
+    permissions={"projects.read"},
+)
+async def read_projects(
+    context: AgentContext,
+    query: ProjectQuery,
+) -> list[dict[str, str]]:
+    repository = context.services["projects"]
+    return await repository.list(category=query.category)
+
+
+async def main() -> None:
+    agent = Agent(
+        name="portfolio",
+        model=OpenAIResponsesProvider(
+            model="your-model-id",
+            instructions="Help visitors discover relevant products.",
+            store=False,
+        ),
+        tools=[read_projects],
+        permissions={"projects.read"},
+    )
+    result = await agent.run(
+        AgentInput(text="Show me the games"),
+        context=AgentContext(
+            session_id="session-id",
+            permissions=frozenset({"projects.read"}),
+            services={"projects": your_repository},
+        ),
+    )
+    print(result.text)
+
+
+asyncio.run(main())
+```
+
+`OPENAI_API_KEY` is read by the OpenAI SDK from the server environment. The
+runtime never stores it and it must never be exposed to browser code.
+
+## Runtime capabilities
+
+- Provider-neutral async agent loop and deterministic fake provider.
+- Typed Pydantic tool inputs and deny-by-default permission intersection.
+- Approval, idempotency, timeout, and retry handling for side effects.
+- Session, run, event, and audit ports with a SQLite reference adapter.
+- SSE event fan-out and trace propagation.
+- Durable task graphs, workers, checkpoints, mailbox control, resource locks,
+  cancellation, and bounded concurrency.
+- Optional OpenAI Responses API adapter.
+
+## Side effects
+
+Tools marked `reversible` or `destructive` receive a runtime idempotency key.
+Set `requires_approval=True` and supply an application-owned `ApprovalGate` for
+publishing, deleting, deploying, calling, or sending messages. Applications
+must still perform authorization inside their own service boundary.
+
+## Coding-agent handoff
+
+When asking another coding agent to integrate this package, provide the root
+repository files `AGENTS.md` and `docs/consumer-agent-brief.md`. The complete,
+provider-free example is in `examples/basic-agent`.

kaiwen_agent-0.1.0a1/README.md

@@ -0,0 +1,91 @@
+# kaiwen-agent
+
+Provider-neutral, asynchronous Python runtime for building tool-using agents.
+Product applications own their prompts, domain tools, authorization context,
+persistence choice, and HTTP surface.
+
+```bash
+pip install "kaiwen-agent[openai]"
+```
+
+## Minimal agent
+
+```python
+import asyncio
+
+from pydantic import BaseModel
+
+from kaiwen_agent import Agent, AgentContext, tool
+from kaiwen_agent.models.openai import OpenAIResponsesProvider
+from kaiwen_agent.types import AgentInput
+
+
+class ProjectQuery(BaseModel):
+    category: str | None = None
+
+
+@tool(
+    name="projects.read",
+    description="List projects visible to the current user",
+    input_model=ProjectQuery,
+    permissions={"projects.read"},
+)
+async def read_projects(
+    context: AgentContext,
+    query: ProjectQuery,
+) -> list[dict[str, str]]:
+    repository = context.services["projects"]
+    return await repository.list(category=query.category)
+
+
+async def main() -> None:
+    agent = Agent(
+        name="portfolio",
+        model=OpenAIResponsesProvider(
+            model="your-model-id",
+            instructions="Help visitors discover relevant products.",
+            store=False,
+        ),
+        tools=[read_projects],
+        permissions={"projects.read"},
+    )
+    result = await agent.run(
+        AgentInput(text="Show me the games"),
+        context=AgentContext(
+            session_id="session-id",
+            permissions=frozenset({"projects.read"}),
+            services={"projects": your_repository},
+        ),
+    )
+    print(result.text)
+
+
+asyncio.run(main())
+```
+
+`OPENAI_API_KEY` is read by the OpenAI SDK from the server environment. The
+runtime never stores it and it must never be exposed to browser code.
+
+## Runtime capabilities
+
+- Provider-neutral async agent loop and deterministic fake provider.
+- Typed Pydantic tool inputs and deny-by-default permission intersection.
+- Approval, idempotency, timeout, and retry handling for side effects.
+- Session, run, event, and audit ports with a SQLite reference adapter.
+- SSE event fan-out and trace propagation.
+- Durable task graphs, workers, checkpoints, mailbox control, resource locks,
+  cancellation, and bounded concurrency.
+- Optional OpenAI Responses API adapter.
+
+## Side effects
+
+Tools marked `reversible` or `destructive` receive a runtime idempotency key.
+Set `requires_approval=True` and supply an application-owned `ApprovalGate` for
+publishing, deleting, deploying, calling, or sending messages. Applications
+must still perform authorization inside their own service boundary.
+
+## Coding-agent handoff
+
+When asking another coding agent to integrate this package, provide the root
+repository files `AGENTS.md` and `docs/consumer-agent-brief.md`. The complete,
+provider-free example is in `examples/basic-agent`.

kaiwen_agent-0.1.0a1/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["hatchling>=1.27,<1.32"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kaiwen-agent"
+version = "0.1.0a1"
+description = "Provider-neutral asynchronous agent runtime"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Kaiwen" }]
+keywords = ["agent", "ai", "asyncio", "openai", "tools"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = [
+  "pydantic>=2.10,<3",
+]
+
+[project.urls]
+Homepage = "https://github.com/ImtheKaiwen/kaiwen-agent-platform"
+Documentation = "https://github.com/ImtheKaiwen/kaiwen-agent-platform/tree/main/docs"
+Repository = "https://github.com/ImtheKaiwen/kaiwen-agent-platform.git"
+Issues = "https://github.com/ImtheKaiwen/kaiwen-agent-platform/issues"
+
+[project.optional-dependencies]
+openai = [
+  "openai>=2,<3",
+]
+dev = [
+  "mypy>=1.14,<2",
+  "python-dotenv>=1.1,<2",
+  "pytest>=8.3,<9",
+  "ruff>=0.9,<1",
+  "openai>=2,<3",
+]
+release = [
+  "build>=1.2,<2",
+  "twine>=6,<7",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kaiwen_agent"]
+
+[tool.pytest.ini_options]
+addopts = "-q -p no:cacheprovider"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+packages = ["kaiwen_agent"]

kaiwen_agent-0.1.0a1/src/kaiwen_agent/__init__.py

@@ -0,0 +1,18 @@
+from kaiwen_agent.agent import Agent
+from kaiwen_agent.context import AgentContext
+from kaiwen_agent.models.base import ModelProvider
+from kaiwen_agent.tools.approval import ApprovalGate, ApprovalRequest
+from kaiwen_agent.tools.decorator import tool
+from kaiwen_agent.tools.definition import RetryPolicy
+from kaiwen_agent.tools.execution import ToolExecutor
+
+__all__ = [
+    "Agent",
+    "AgentContext",
+    "ApprovalGate",
+    "ApprovalRequest",
+    "ModelProvider",
+    "RetryPolicy",
+    "ToolExecutor",
+    "tool",
+]

kaiwen_agent-0.1.0a1/src/kaiwen_agent/agent.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from uuid import uuid4
+
+from kaiwen_agent.context import AgentContext
+from kaiwen_agent.events import AgentEvent, EventSink, EventType, InMemoryEventSink
+from kaiwen_agent.models.base import ModelProvider
+from kaiwen_agent.sessions import InMemoryRunStore, RunStore
+from kaiwen_agent.tools.definition import ToolDefinition
+from kaiwen_agent.tools.execution import ToolExecutor
+from kaiwen_agent.tools.registry import ToolRegistry
+from kaiwen_agent.types import AgentInput, AgentResult, AgentRun, ModelUsage, ToolResult
+
+
+class Agent:
+    def __init__(
+        self,
+        *,
+        name: str,
+        model: ModelProvider,
+        tools: list[ToolDefinition] | None = None,
+        permissions: set[str] | frozenset[str] | None = None,
+        event_sink: EventSink | None = None,
+        run_store: RunStore | None = None,
+        tool_executor: ToolExecutor | None = None,
+        max_steps: int = 8,
+    ) -> None:
+        if max_steps < 1:
+            raise ValueError("max_steps must be at least 1")
+        self.name = name
+        self.model = model
+        self.registry = ToolRegistry(tools or [])
+        self.permissions = frozenset(permissions or set())
+        self.event_sink = event_sink or InMemoryEventSink()
+        self.run_store = run_store or InMemoryRunStore()
+        self.tool_executor = tool_executor or ToolExecutor()
+        self.max_steps = max_steps
+
+    async def run(self, agent_input: AgentInput, *, context: AgentContext) -> AgentResult:
+        trace_id = context.trace_id or f"trace_{uuid4().hex}"
+        effective_context = AgentContext(
+            session_id=context.session_id,
+            trace_id=trace_id,
+            permissions=context.permissions & self.permissions,
+            services=context.services,
+            metadata=context.metadata,
+        )
+        run = AgentRun(session_id=context.session_id, status="running")
+        await self.run_store.save(run)
+        await self._emit("run.started", run, trace_id, {"agent": self.name})
+        tool_results: list[ToolResult] = []
+        pending_tool_results: list[ToolResult] = []
+        previous_response_id: str | None = None
+        total_usage = ModelUsage()
+
+        try:
+            for step in range(self.max_steps):
+                response = await self.model.respond(
+                    agent_input,
+                    context=effective_context,
+                    tools=self.registry.definitions(),
+                    tool_results=pending_tool_results,
+                    previous_response_id=previous_response_id,
+                )
+                pending_tool_results = []
+                previous_response_id = response.provider_response_id or previous_response_id
+                if response.usage is not None:
+                    total_usage.input_tokens += response.usage.input_tokens
+                    total_usage.output_tokens += response.usage.output_tokens
+                    total_usage.total_tokens += response.usage.total_tokens
+                    await self._emit(
+                        "run.status",
+                        run,
+                        trace_id,
+                        {
+                            "kind": "model_usage",
+                            "model": response.model or "unknown",
+                            **response.usage.model_dump(),
+                        },
+                    )
+                if not response.tool_calls:
+                    result = AgentResult(
+                        run_id=run.id,
+                        session_id=run.session_id,
+                        text=response.text or "",
+                        status="completed",
+                        tool_results=tool_results,
+                        structured_output=response.structured_output,
+                        usage=total_usage,
+                    )
+                    run.status = "completed"
+                    run.completed_at = datetime.now(UTC)
+                    await self.run_store.save(run)
+                    await self._emit(
+                        "run.completed", run, trace_id, {"step": step, "text": result.text}
+                    )
+                    return result
+
+                for call in response.tool_calls:
+                    definition = self.registry.get(call.name)
+                    tool_result = await self.tool_executor.execute(
+                        definition,
+                        call,
+                        effective_context,
+                        execution_scope=run.id,
+                        emit=lambda event_type, payload: self._emit(
+                            event_type, run, trace_id, payload
+                        ),
+                    )
+                    tool_results.append(tool_result)
+                    pending_tool_results.append(tool_result)
+
+            raise RuntimeError(f"Agent exceeded max_steps={self.max_steps}")
+        except Exception as error:
+            run.status = "failed"
+            run.completed_at = datetime.now(UTC)
+            await self.run_store.save(run)
+            await self._emit("run.failed", run, trace_id, {"error_type": type(error).__name__})
+            raise
+
+    async def _emit(
+        self,
+        event_type: EventType,
+        run: AgentRun,
+        trace_id: str,
+        payload: dict[str, object],
+    ) -> None:
+        await self.event_sink.append(
+            AgentEvent(
+                type=event_type,
+                trace_id=trace_id,
+                session_id=run.session_id,
+                payload=payload,
+            )
+        )

kaiwen_agent-0.1.0a1/src/kaiwen_agent/audit.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import re
+from datetime import datetime
+from typing import Any, Literal, Protocol
+from uuid import uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from kaiwen_agent.types import utc_now
+
+
+class AuditRecord(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    id: str = Field(default_factory=lambda: f"audit_{uuid4().hex}")
+    trace_id: str
+    session_id: str
+    action: str
+    outcome: Literal["succeeded", "failed", "denied"]
+    details: dict[str, Any] = Field(default_factory=dict)
+    timestamp: datetime = Field(default_factory=utc_now)
+
+
+class AuditStore(Protocol):
+    async def append_audit(self, record: AuditRecord) -> None: ...
+
+    async def list_audit(self, *, trace_id: str | None = None) -> list[AuditRecord]: ...
+
+
+class InMemoryAuditStore:
+    def __init__(self) -> None:
+        self.records: list[AuditRecord] = []
+
+    async def append_audit(self, record: AuditRecord) -> None:
+        self.records.append(record.model_copy(deep=True))
+
+    async def list_audit(self, *, trace_id: str | None = None) -> list[AuditRecord]:
+        records = self.records
+        if trace_id is not None:
+            records = [record for record in records if record.trace_id == trace_id]
+        return [record.model_copy(deep=True) for record in records]
+
+
+class SecretRedactor:
+    _secret_keys = re.compile(
+        r"(^|_)(api_?key|authorization|cookie|password|secret|token)($|_)", re.IGNORECASE
+    )
+    _secret_values = (
+        re.compile(r"\bsk-[A-Za-z0-9_-]{12,}\b"),
+        re.compile(r"\bBearer\s+[A-Za-z0-9._~+/-]+=*", re.IGNORECASE),
+    )
+
+    def redact(self, value: Any, *, key: str | None = None) -> Any:
+        if key is not None and self._secret_keys.search(key):
+            return "[REDACTED]"
+        if isinstance(value, dict):
+            return {
+                item_key: self.redact(item_value, key=str(item_key))
+                for item_key, item_value in value.items()
+            }
+        if isinstance(value, list):
+            return [self.redact(item) for item in value]
+        if isinstance(value, tuple):
+            return tuple(self.redact(item) for item in value)
+        if isinstance(value, str):
+            redacted = value
+            for pattern in self._secret_values:
+                redacted = pattern.sub("[REDACTED]", redacted)
+            return redacted
+        return value
+
+
+class RedactingAuditStore:
+    def __init__(self, store: AuditStore, redactor: SecretRedactor | None = None) -> None:
+        self.store = store
+        self.redactor = redactor or SecretRedactor()
+
+    async def append_audit(self, record: AuditRecord) -> None:
+        clean = record.model_copy(update={"details": self.redactor.redact(record.details)})
+        await self.store.append_audit(clean)
+
+    async def list_audit(self, *, trace_id: str | None = None) -> list[AuditRecord]:
+        return await self.store.list_audit(trace_id=trace_id)

kaiwen_agent-0.1.0a1/src/kaiwen_agent/context.py

@@ -0,0 +1,12 @@
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class AgentContext:
+    session_id: str
+    trace_id: str | None = None
+    permissions: frozenset[str] = field(default_factory=frozenset)
+    services: Mapping[str, Any] = field(default_factory=dict)
+    metadata: Mapping[str, Any] = field(default_factory=dict)

kaiwen_agent-0.1.0a1/src/kaiwen_agent/control/__init__.py

@@ -0,0 +1,17 @@
+from kaiwen_agent.control.checkpoints import (
+    CheckpointStore,
+    InMemoryCheckpointStore,
+    TaskCheckpoint,
+)
+from kaiwen_agent.control.mailbox import ControlMessage, InMemoryMailbox, TaskCancelledError
+from kaiwen_agent.control.runtime import RunControl
+
+__all__ = [
+    "CheckpointStore",
+    "ControlMessage",
+    "InMemoryCheckpointStore",
+    "InMemoryMailbox",
+    "RunControl",
+    "TaskCancelledError",
+    "TaskCheckpoint",
+]

kaiwen_agent-0.1.0a1/src/kaiwen_agent/control/checkpoints.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Protocol
+from uuid import uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from kaiwen_agent.types import utc_now
+
+
+class TaskCheckpoint(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    id: str = Field(default_factory=lambda: f"checkpoint_{uuid4().hex}")
+    task_id: str
+    sequence: int = Field(ge=1)
+    state: dict[str, Any] = Field(default_factory=dict)
+    created_at: datetime = Field(default_factory=utc_now)
+
+
+class CheckpointStore(Protocol):
+    async def save_checkpoint(self, checkpoint: TaskCheckpoint) -> None: ...
+
+    async def latest_checkpoint(self, task_id: str) -> TaskCheckpoint | None: ...
+
+
+class InMemoryCheckpointStore:
+    def __init__(self) -> None:
+        self._checkpoints: dict[str, list[TaskCheckpoint]] = {}
+
+    async def save_checkpoint(self, checkpoint: TaskCheckpoint) -> None:
+        self._checkpoints.setdefault(checkpoint.task_id, []).append(
+            checkpoint.model_copy(deep=True)
+        )
+
+    async def latest_checkpoint(self, task_id: str) -> TaskCheckpoint | None:
+        checkpoints = self._checkpoints.get(task_id, [])
+        return checkpoints[-1].model_copy(deep=True) if checkpoints else None

kaiwen_agent-0.1.0a1/src/kaiwen_agent/control/mailbox.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import asyncio
+from collections import defaultdict, deque
+from datetime import datetime
+from typing import Any, Literal
+from uuid import uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from kaiwen_agent.types import utc_now
+
+ControlType = Literal["instruction", "cancel", "pause", "resume", "approval"]
+
+
+class ControlMessage(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    id: str = Field(default_factory=lambda: f"control_{uuid4().hex}")
+    type: ControlType
+    content: str = ""
+    created_by: str
+    created_at: datetime = Field(default_factory=utc_now)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class InMemoryMailbox:
+    def __init__(self) -> None:
+        self._messages: dict[str, deque[ControlMessage]] = defaultdict(deque)
+        self._conditions: dict[str, asyncio.Condition] = defaultdict(asyncio.Condition)
+        self._paused: set[str] = set()
+        self._cancelled: set[str] = set()
+
+    async def send(self, task_id: str, message: ControlMessage) -> None:
+        condition = self._conditions[task_id]
+        async with condition:
+            self._messages[task_id].append(message.model_copy(deep=True))
+            if message.type == "cancel":
+                self._cancelled.add(task_id)
+            elif message.type == "pause":
+                self._paused.add(task_id)
+            elif message.type == "resume":
+                self._paused.discard(task_id)
+            condition.notify_all()
+
+    async def checkpoint(self, task_id: str) -> list[ControlMessage]:
+        condition = self._conditions[task_id]
+        async with condition:
+            if task_id in self._cancelled:
+                raise TaskCancelledError(f"Task cancelled: {task_id}")
+            while task_id in self._paused:
+                await condition.wait()
+                if task_id in self._cancelled:
+                    raise TaskCancelledError(f"Task cancelled: {task_id}")
+            messages = list(self._messages[task_id])
+            self._messages[task_id].clear()
+            return [message.model_copy(deep=True) for message in messages]
+
+
+class TaskCancelledError(Exception):
+    pass