base-agentkit 0.1.0__py3-none-any.whl

agentkit/workspace/fs.py

@@ -0,0 +1,288 @@
+"""Workspace filesystem facade with strict path isolation."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from agentkit.errors import WorkspaceError
+
+
+class WorkspaceFS:
+    """Read/write operations scoped to a single workspace root."""
+
+    def __init__(self, root: str | Path) -> None:
+        """Create a workspace filesystem facade and ensure root exists.
+
+        Args:
+            root: Workspace root directory.
+
+        Returns:
+            None
+        """
+        self.root = Path(root).expanduser().resolve()
+        self.root.mkdir(parents=True, exist_ok=True)
+
+    def resolve_path(self, path: str | Path) -> Path:
+        """Resolve a path and enforce workspace containment.
+
+        Args:
+            path: Absolute or workspace-relative path.
+
+        Returns:
+            pathlib.Path: Fully resolved path within the workspace root.
+
+        Raises:
+            agentkit.errors.WorkspaceError: If the resolved path escapes workspace
+                boundaries.
+        """
+        candidate = Path(path)
+        if not candidate.is_absolute():
+            candidate = self.root / candidate
+        resolved = candidate.expanduser().resolve(strict=False)
+
+        if resolved != self.root and self.root not in resolved.parents:
+            raise WorkspaceError(f"Path escapes workspace: {path}")
+        return resolved
+
+    def exists(self, path: str | Path) -> bool:
+        """Check whether a path exists inside the workspace.
+
+        Args:
+            path: Absolute or workspace-relative path.
+
+        Returns:
+            bool: ``True`` when the resolved path exists.
+
+        Raises:
+            agentkit.errors.WorkspaceError: If the path escapes workspace boundaries.
+        """
+        return self.resolve_path(path).exists()
+
+    def is_file(self, path: str | Path) -> bool:
+        """Check whether a path points to a file inside the workspace.
+
+        Args:
+            path: Absolute or workspace-relative path.
+
+        Returns:
+            bool: ``True`` when the resolved path exists and is a file.
+
+        Raises:
+            agentkit.errors.WorkspaceError: If the path escapes workspace boundaries.
+        """
+        return self.resolve_path(path).is_file()
+
+    def is_dir(self, path: str | Path) -> bool:
+        """Check whether a path points to a directory inside the workspace.
+
+        Args:
+            path: Absolute or workspace-relative path.
+
+        Returns:
+            bool: ``True`` when the resolved path exists and is a directory.
+
+        Raises:
+            agentkit.errors.WorkspaceError: If the path escapes workspace boundaries.
+        """
+        return self.resolve_path(path).is_dir()
+
+    def mkdir(
+        self, path: str | Path, *, parents: bool = True, exist_ok: bool = True
+    ) -> Path:
+        """Create a directory inside the workspace.
+
+        Args:
+            path: Absolute or workspace-relative directory path.
+            parents: Whether to create missing parent directories.
+            exist_ok: Whether existing directory is allowed.
+
+        Returns:
+            pathlib.Path: Resolved directory path.
+
+        Raises:
+            agentkit.errors.WorkspaceError: If the path escapes workspace boundaries.
+            FileExistsError: If target exists and ``exist_ok`` is ``False``.
+        """
+        target = self.resolve_path(path)
+        target.mkdir(parents=parents, exist_ok=exist_ok)
+        return target
+
+    def list_dir(self, path: str | Path = ".") -> list[str]:
+        """List entries in a workspace directory.
+
+        Args:
+            path: Absolute or workspace-relative directory path.
+
+        Returns:
+            list[str]: Sorted entry names.
+
+        Raises:
+            agentkit.errors.WorkspaceError: If path is outside workspace, missing, or
+                not a directory.
+        """
+        target = self.resolve_path(path)
+        if not target.exists():
+            raise WorkspaceError(f"Directory does not exist: {path}")
+        if not target.is_dir():
+            raise WorkspaceError(f"Not a directory: {path}")
+        return sorted(entry.name for entry in target.iterdir())
+
+    def read_text(self, path: str | Path, *, encoding: str = "utf-8") -> str:
+        """Read UTF-8 text from a workspace file.
+
+        Args:
+            path: Absolute or workspace-relative file path.
+            encoding: Text encoding used for reading.
+
+        Returns:
+            str: File content.
+
+        Raises:
+            agentkit.errors.WorkspaceError: If path is outside workspace, missing, or
+                not a file.
+        """
+        target = self.resolve_path(path)
+        if not target.exists():
+            raise WorkspaceError(f"File does not exist: {path}")
+        if not target.is_file():
+            raise WorkspaceError(f"Not a file: {path}")
+        return target.read_text(encoding=encoding)
+
+    def write_text(
+        self,
+        path: str | Path,
+        text: str,
+        *,
+        encoding: str = "utf-8",
+        overwrite: bool = True,
+    ) -> None:
+        """Write text to a workspace file.
+
+        Args:
+            path: Absolute or workspace-relative file path.
+            text: Text content to persist.
+            encoding: Text encoding used for writing.
+            overwrite: Whether existing files may be replaced.
+
+        Returns:
+            None
+
+        Raises:
+            agentkit.errors.WorkspaceError: If path escapes workspace or overwrite is
+                disallowed for an existing file.
+        """
+        target = self.resolve_path(path)
+        if target.exists() and not overwrite:
+            raise WorkspaceError(f"File already exists and overwrite=False: {path}")
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(text, encoding=encoding)
+
+    def append_text(
+        self, path: str | Path, text: str, *, encoding: str = "utf-8"
+    ) -> None:
+        """Append text to a workspace file, creating it if needed.
+
+        Args:
+            path: Absolute or workspace-relative file path.
+            text: Text content to append.
+            encoding: Text encoding used for writing.
+
+        Returns:
+            None
+
+        Raises:
+            agentkit.errors.WorkspaceError: If path escapes workspace boundaries.
+        """
+        target = self.resolve_path(path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        with target.open("a", encoding=encoding) as f:
+            f.write(text)
+
+    def edit_text(
+        self,
+        path: str | Path,
+        old: str,
+        new: str,
+        *,
+        count: int | None = None,
+        encoding: str = "utf-8",
+    ) -> int:
+        """Replace text occurrences in a workspace file.
+
+        Args:
+            path: Absolute or workspace-relative file path.
+            old: Substring to replace.
+            new: Replacement substring.
+            count: Optional maximum number of replacements.
+            encoding: Text encoding used for read/write operations.
+
+        Returns:
+            int: Number of replacements applied.
+
+        Raises:
+            agentkit.errors.WorkspaceError: If ``old`` is empty, ``count`` is
+                negative, or the path is invalid.
+        """
+        if old == "":
+            raise WorkspaceError("edit_text 'old' pattern must not be empty.")
+
+        content = self.read_text(path, encoding=encoding)
+        occurrences = content.count(old)
+        if occurrences == 0:
+            return 0
+
+        if count is None:
+            updated = content.replace(old, new)
+            replaced = occurrences
+        else:
+            if count < 0:
+                raise WorkspaceError("edit_text 'count' must be >= 0 when provided.")
+            updated = content.replace(old, new, count)
+            replaced = min(occurrences, count)
+
+        self.write_text(path, updated, encoding=encoding, overwrite=True)
+        return replaced
+
+    def read_json(self, path: str | Path) -> Any:
+        """Read and decode JSON from a workspace file.
+
+        Args:
+            path: Absolute or workspace-relative JSON file path.
+
+        Returns:
+            Any: Decoded JSON payload.
+
+        Raises:
+            agentkit.errors.WorkspaceError: If the path is invalid.
+            json.JSONDecodeError: If file content is not valid JSON.
+        """
+        return json.loads(self.read_text(path))
+
+    def write_json(
+        self,
+        path: str | Path,
+        data: Any,
+        *,
+        ensure_ascii: bool = False,
+        indent: int = 2,
+    ) -> None:
+        """Encode and write JSON to a workspace file.
+
+        Args:
+            path: Absolute or workspace-relative destination path.
+            data: JSON-serializable payload.
+            ensure_ascii: Whether to escape non-ASCII characters.
+            indent: Pretty-print indentation size.
+
+        Returns:
+            None
+
+        Raises:
+            agentkit.errors.WorkspaceError: If path is invalid.
+            TypeError: If ``data`` contains non-serializable values.
+        """
+        self.write_text(
+            path, json.dumps(data, ensure_ascii=ensure_ascii, indent=indent)
+        )

agentkit/workspace/layout.py

@@ -0,0 +1,33 @@
+"""Workspace folder layout helpers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable
+
+from agentkit.constants import DEFAULT_WORKSPACE_DIRS
+
+
+def init_workspace_layout(
+    root: str | Path,
+    *,
+    extra_dirs: Iterable[str] | None = None,
+) -> Path:
+    """Create default workspace directories under the given root.
+
+    Args:
+        root: Workspace root directory path.
+        extra_dirs: Optional additional directory names to create.
+
+    Returns:
+        pathlib.Path: Resolved workspace root path.
+    """
+    root_path = Path(root).expanduser().resolve()
+    root_path.mkdir(parents=True, exist_ok=True)
+
+    dirs = list(DEFAULT_WORKSPACE_DIRS)
+    if extra_dirs:
+        dirs.extend(extra_dirs)
+    for item in dirs:
+        (root_path / item).mkdir(parents=True, exist_ok=True)
+    return root_path

base_agentkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: base-agentkit
+Version: 0.1.0
+Summary: Workspace-isolated Python framework for building tool-using LLM agents.
+Keywords: agents,llm,tool-calling,workspace,ai
+Author: sii-nyc
+Author-email: sii-nyc <253108120111@sii.edu.cn>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Dist: openai>=2.21.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: requests>=2.32.5
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/Inkjourney/agentkit
+Project-URL: Repository, https://github.com/Inkjourney/agentkit
+Project-URL: Documentation, https://github.com/Inkjourney/agentkit/tree/main/docs/agentkit
+Project-URL: Issues, https://github.com/Inkjourney/agentkit/issues
+Description-Content-Type: text/markdown
+
+# AgentKit
+
+一个基于 LLM 的通用 Agent 框架，支持 workspace 隔离、统一 LLM 抽象、工具调用循环、CLI 与 Python SDK。
+
+## 当前能力
+
+- workspace 强隔离：所有读写通过 `WorkspaceFS`
+- 统一 LLM 抽象：`ConversationItem` / `ConversationState` / `UnifiedLLMRequest` / `UnifiedLLMResponse`
+- Provider 支持（同步、非流式、文本）
+  - OpenAI (`responses` / `chat_completions`)
+  - Anthropic (`messages`)
+  - Gemini (`generateContent`)
+  - Qwen（OpenAI-compatible `chat_completions`）
+  - vLLM（OpenAI-compatible `chat_completions`）
+- 工具系统：注册式工具机制，工具模块放在 `src/agentkit/tools/library/`
+- Agent loop：模型推理与工具执行闭环，受 step/time budget 约束
+- runlog：每次任务写入 `workspace/logs/run_<run_id>.jsonl`
+
+## 状态
+
+- 当前仓库包含针对 Agent loop、CLI、工具系统、runlog 以及 OpenAI / Anthropic / Gemini / Qwen / vLLM provider 适配层的单元测试
+- 尚未提供针对真实上游 API 的集成 smoke test，因此正式发布前仍建议用目标模型做一次端到端验证
+
+## 文档
+
+详细使用说明和完整文档见 `docs/agentkit/`。
+
+## 从源码安装
+
+```bash
+uv sync
+uv run agentkit --help
+```
+
+## 从 PyPI 安装
+
+```bash
+pip install base-agentkit
+agentkit --help
+```
+
+安装后的导入路径和 CLI 名称保持不变：
+
+```python
+from agentkit import create_agent
+```
+
+## 配置示例
+
+### vLLM
+
+```yaml
+workspace:
+  root: "./vllm_workspace"
+
+provider:
+  kind: "vllm"
+  model: "glm-5"
+  openai_api_variant: "chat_completions"
+  conversation_mode: "auto"
+  base_url: "http://localhost:8000/v1"
+  api_key: "empty"
+  temperature: 0.8
+  timeout_s: 600
+  retries: 2
+  enable_thinking: true
+
+agent:
+  system_prompt: "You are a helpful agent. Use tools when needed."
+  budget:
+    max_steps: 200
+    time_budget_s: 1800
+    max_input_chars: 180000
+
+tools:
+  allowed:
+    - "view"
+    - "create_file"
+    - "str_replace"
+    - "word_count"
+
+runlog:
+  enabled: true
+  redact: true
+  max_text_chars: 20000
+```
+
+## CLI 运行
+
+```bash
+export OPENAI_API_KEY="your-key"
+uv run agentkit --config path/to/config.yaml run --task "列出当前 workspace 的文件"
+```
+
+## Python SDK
+
+```python
+from agentkit import create_agent
+
+agent = create_agent("path/to/config.yaml")
+report = agent.run("在 workspace 里新建 notes/todo.txt 并写入今天计划")
+print(report.final_output)
+```
+
+## 项目结构
+
+核心实现位于 `src/agentkit/`：
+
+- `config/`: 配置结构与加载
+- `workspace/`: 强隔离文件系统和目录布局
+- `llm/`: 统一抽象、provider base/factory 与四平台 adapter
+- `tools/`: 工具抽象、注册表与自动加载
+- `agent/`: budget、report、runtime、Agent loop
+- `runlog/`: 结构化事件、event sink 与 JSONL runlog
+- `cli/`: 命令行入口

base_agentkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,51 @@
+agentkit/__init__.py,sha256=uvPo2sQhLsW9w4OhwlwVwNloHF6UJgqInHX-q59112M,960
+agentkit/agent/__init__.py,sha256=XwEe83HEobpihELZZR-gGjjjS4_LHGuOtuKibibNo0g,189
+agentkit/agent/agent.py,sha256=lNHA9YNpbOcp2doqKHTMYCPDddXzJ4oOINk6S_CU8EY,13237
+agentkit/agent/budgets.py,sha256=imnIWbO9u3hbeldlfvWFBrOhUm-FCcz7KEp5uOkDuio,1516
+agentkit/agent/report.py,sha256=U9ncOPd1LpghN-pycnH9KU89PxuWwmTTt2ev3tTslkc,5849
+agentkit/agent/tool_runtime.py,sha256=HXt8IkDCDPlsjWEJPLfRyAykGk_v-3sK9zSKVL0uWZc,3004
+agentkit/cli/__init__.py,sha256=ehsfo9JFja2dwYRH0NSZB9DPesATUHcF_gTIy1jlwA4,80
+agentkit/cli/main.py,sha256=uco0Wyr4MF04DZakv1LSF3mDxVc2Vpb2Nt4JX6PXszM,3022
+agentkit/config/__init__.py,sha256=q0bAMgLAxOGN3d-bVZWtpxbR8ZO77zV5S_VeKAQ1ylU,420
+agentkit/config/loader.py,sha256=pBX3eQGXhUayCqzMp5t-yqz_wzItLZVGvsUpChmVVLc,3232
+agentkit/config/provider_defaults.py,sha256=HQehlBljMFswBB9oh6GBoTjpkE7kA-BQ2iGgyNyPdeg,3095
+agentkit/config/schema.py,sha256=8K0KUpyfsdKotPkgeyIyEOdU0XBKnI31rCvv3cPBzwc,4995
+agentkit/constants.py,sha256=R6o6ycmzQLvQTyZjhOn1cUu_3BXRgyC6IDXnugNZwTw,422
+agentkit/errors.py,sha256=yQ7MQ_lAOl_tDRl21d9Z0wnty2uykDJT0oW0HlHpkZ0,1515
+agentkit/llm/__init__.py,sha256=1LDpEx1izf6MIwQSaoLqKPuOFPmkU7frYhgvpMNCYZs,1237
+agentkit/llm/base.py,sha256=bFz6QJJYrVuqHvgG7FhZDB7EDHBnH2h7wM3Z4Fzc7DQ,977
+agentkit/llm/factory.py,sha256=L5HtP39llds8NqmO5B9sPB-xBJcD6IPJAW-fSn7Ch7A,1103
+agentkit/llm/providers/__init__.py,sha256=iQcnrkBfqaa4cMARSEQFKmBz9HjR9WkVVnTI6Yvn9M4,389
+agentkit/llm/providers/anthropic_provider.py,sha256=VPldD0l14kDR-Z6jpIMwSq6gf9oxHxB2VhcWPDXvIE0,12537
+agentkit/llm/providers/gemini_provider.py,sha256=ZABSvjjLZavVHYtburT39g56sBUPtB0mUYhnsHcZHKs,14122
+agentkit/llm/providers/openai_provider.py,sha256=LinoXstrWtmYiY2vSDM_jfHyCXvQadz-99l9utwqWDU,31693
+agentkit/llm/providers/qwen_provider.py,sha256=k_QnwnqO0wzlbn0LGqVIEIXU1irPRCYe7E97GC0ZS0E,1180
+agentkit/llm/providers/vllm_provider.py,sha256=zViTsue8B4ZwJll-NJdg9QNxd8qkGpQh7vnTvy3A3L8,1622
+agentkit/llm/types.py,sha256=ltFTvdpvBSsEDrhLzYWx4IGG1w50EkYmCzNnawYIqDQ,6741
+agentkit/llm/usage.py,sha256=JP6lfgKOAqmEG0AU8Q0juDrlEEHQrrET_FSu1a8P0Fo,2631
+agentkit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agentkit/runlog/__init__.py,sha256=G0WeFurv3s9Q-hJJ_gULIDS6MMvUZV5G18RAO_0oPio,348
+agentkit/runlog/events.py,sha256=apK0aC2Uc-5uAlZumnMxy_UK_0yh8874qcTjO-PX3Pk,1698
+agentkit/runlog/jsonl.py,sha256=hsQvHuR8QcYgoP9vIbXpTXxdVnP5K-2c0BbiUStCdNQ,3557
+agentkit/runlog/recorder.py,sha256=G5DM-H2j9BbTZqQQep0oAEcFZhsSdaPz4Yn3r47qVYM,2806
+agentkit/runlog/sinks.py,sha256=nMophq_23jAhuTvLaph_cSrAGAFqVfu51sJ5gQc3Y04,384
+agentkit/tools/__init__.py,sha256=dwRU6OXsbSfNFgw1s9BbF2wLIaZKyYhsKKva8TTnQ4w,401
+agentkit/tools/base.py,sha256=DOasFvdpAicIycefwsli320tXdctn3laBdjnfkxoM7E,4592
+agentkit/tools/library/__init__.py,sha256=KlE_0uCQBJkdqwXKEm6R_lo2qkE97Spq8JglrNC_4ek,256
+agentkit/tools/library/_fs_common.py,sha256=tWNi4K1wdeSNxg3R6Sz9UjnnJn_gvZKRFtZQD0A_PRI,11709
+agentkit/tools/library/create_file.py,sha256=O_S_k3fV8864Pmwyy0sOZlF8bKQ_Oq8KU1RMI7oOWaM,6942
+agentkit/tools/library/fs_tools.py,sha256=q-JkUles2HGyRbu2XHjbokmY8hLRO5_89qkY0L1NrJ8,608
+agentkit/tools/library/str_replace.py,sha256=Rx-y9Cj-8ckyWnSMMnOA4QBJXQCFjkYoo9g1h3gOvwQ,9939
+agentkit/tools/library/view.py,sha256=FbBQwbVvke5usdAs4-111uC4C0l33fax1IgQ4CwuCJE,15137
+agentkit/tools/library/word_count.py,sha256=y0RE5GMoL-4xackze5BA_702eeHTkAtB5b1sNjkvFCM,4975
+agentkit/tools/loader.py,sha256=yeTRqepnmWCqTHwMUUxo4OQD83aKxcsVtE7hJE5kas8,2665
+agentkit/tools/registry.py,sha256=5NvSczLj1Xx9qY62edLHACtm-IOZm7oYS37glOaEuJg,9824
+agentkit/tools/types.py,sha256=34pyZKVDOs6Cx2hntcfnzywywZq90g-7v2y6uwWBA10,2988
+agentkit/workspace/__init__.py,sha256=G59NG5d4iz5k2oyLnDECgxvkZgn1DApPfg8S2m1LNSA,166
+agentkit/workspace/fs.py,sha256=wK04_2ntuoZKXz5EvnDvOYa1fD1DGkLmHQGpkMkV1ZI,9155
+agentkit/workspace/layout.py,sha256=qqqAMT8KJgJEvfAIEgPvmugvYIpV2dtvehCmWVg67DY,857
+base_agentkit-0.1.0.dist-info/licenses/LICENSE,sha256=H_yPvvR29lIsDtuLNx8fxmomlOhH2sGB6kVFK5dpq10,10258
+base_agentkit-0.1.0.dist-info/WHEEL,sha256=mydTeHxOpFHo-DnYhAd_3ATePms-g4rrYvM7wJK8P-U,80
+base_agentkit-0.1.0.dist-info/entry_points.txt,sha256=RHNxUMQqoYnK5ZP4Ukw-cfU7JX9g7ZESDvHC2mriUz4,53
+base_agentkit-0.1.0.dist-info/METADATA,sha256=X4ubZwq-_XtTqOlHLo5v8o2hYEKOGa0cYEiBuKwLlsc,3930
+base_agentkit-0.1.0.dist-info/RECORD,,

base_agentkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.10.9
+Root-Is-Purelib: true
+Tag: py3-none-any

base_agentkit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+agentkit = agentkit.cli.main:main
+