knowlyr-core 0.1.0__tar.gz

knowlyr_core-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Claude Code
+CLAUDE.md
+
+# OS
+.DS_Store
+Thumbs.db

knowlyr_core-0.1.0/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: knowlyr-core
+Version: 0.1.0
+Summary: Shared data models for knowlyr agent toolchain
+Project-URL: Homepage, https://github.com/liuxiaotong/knowlyr-agent
+Project-URL: Documentation, https://github.com/liuxiaotong/knowlyr-agent/tree/main/packages/core
+Project-URL: Repository, https://github.com/liuxiaotong/knowlyr-agent
+Project-URL: Issues, https://github.com/liuxiaotong/knowlyr-agent/issues
+Author-email: Liu Kai <mrliukai@gmail.com>
+License-Expression: MIT
+Keywords: agent,code-agent,data-models,trajectory
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/plain
+
+Shared data models for knowlyr agent toolchain.

knowlyr_core-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "knowlyr-core"
+version = "0.1.0"
+description = "Shared data models for knowlyr agent toolchain"
+readme = {text = "Shared data models for knowlyr agent toolchain.", content-type = "text/plain"}
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Liu Kai", email = "mrliukai@gmail.com" }
+]
+keywords = ["agent", "data-models", "trajectory", "code-agent"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+dependencies = [
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "ruff"]
+
+[project.urls]
+Homepage = "https://github.com/liuxiaotong/knowlyr-agent"
+Documentation = "https://github.com/liuxiaotong/knowlyr-agent/tree/main/packages/core"
+Repository = "https://github.com/liuxiaotong/knowlyr-agent"
+Issues = "https://github.com/liuxiaotong/knowlyr-agent/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/knowlyrcore"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"

knowlyr_core-0.1.0/src/knowlyrcore/__init__.py

@@ -0,0 +1,59 @@
+"""knowlyr-core — 共享数据模型、领域配置与环境协议
+
+提供 knowlyr 生态各子包共用的基础数据类型、领域 Profile、
+Gymnasium 风格 AgentEnv 协议和环境注册表。
+"""
+
+__version__ = "0.1.0"
+
+from knowlyrcore.domain import (
+    BROWSER_PROFILE,
+    CODING_PROFILE,
+    GENERIC_PROFILE,
+    DomainProfile,
+    OutcomeSpec,
+    ToolCategory,
+    ToolSpec,
+    get_domain_profile,
+    list_domain_profiles,
+    load_domain_profile,
+)
+from knowlyrcore.env import AgentEnv, EnvWrapper
+from knowlyrcore.models import TaskInfo, ToolResult
+from knowlyrcore.registry import (
+    EnvSpec,
+    list_envs,
+    make,
+    register,
+    spec,
+)
+from knowlyrcore.timestep import TimeStep
+
+__all__ = [
+    # 数据模型
+    "TaskInfo",
+    "ToolResult",
+    # 领域配置
+    "DomainProfile",
+    "ToolCategory",
+    "ToolSpec",
+    "OutcomeSpec",
+    "CODING_PROFILE",
+    "BROWSER_PROFILE",
+    "GENERIC_PROFILE",
+    "get_domain_profile",
+    "load_domain_profile",
+    "list_domain_profiles",
+    # 环境协议
+    "AgentEnv",
+    "EnvWrapper",
+    "TimeStep",
+    # 注册表
+    "EnvSpec",
+    "register",
+    "make",
+    "list_envs",
+    "spec",
+    # 版本
+    "__version__",
+]

knowlyr_core-0.1.0/src/knowlyrcore/domain.py

@@ -0,0 +1,205 @@
+"""领域配置 — DomainProfile / ToolCategory / ToolSpec / OutcomeSpec.
+
+通过 DomainProfile 声明工具分类和结果判定规则，让 pipeline 支持任意 tool-use agent 领域。
+"""
+
+from __future__ import annotations
+
+import json
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class ToolCategory(str, Enum):
+    """工具功能分类."""
+
+    READ = "read"           # 读取/观察状态
+    WRITE = "write"         # 修改状态
+    SEARCH = "search"       # 搜索/发现
+    EXECUTE = "execute"     # 执行命令
+    NAVIGATE = "navigate"   # 切换上下文/位置
+    SUBMIT = "submit"       # 提交/完成
+    THINK = "think"         # 内部推理，无副作用
+
+
+class ToolSpec(BaseModel):
+    """工具规格定义.
+
+    Attributes:
+        name: 工具主名称
+        category: 功能分类
+        stateful_key: 标识操作目标的参数名 (如 file_path / url / element_id)
+        aliases: 同一工具的别名列表
+    """
+
+    name: str
+    category: ToolCategory
+    stateful_key: str = ""
+    aliases: list[str] = Field(default_factory=list)
+
+
+class OutcomeSpec(BaseModel):
+    """结果判定规格.
+
+    定义如何从 outcome dict 中提取成功/分数信息。
+
+    Attributes:
+        success_field: 布尔成功字段名
+        score_field: 分数字段名 (如 tests_passed)
+        total_field: 总量字段名 (如 tests_total)，与 score_field 配合计算比例
+        partial_credit_field: 手动部分得分字段名
+    """
+
+    success_field: str = "success"
+    score_field: str = ""
+    total_field: str = ""
+    partial_credit_field: str = "partial_credit"
+
+
+class DomainProfile(BaseModel):
+    """领域配置.
+
+    声明式地描述一个 agent 领域的工具集、结果判定、任务字段等。
+
+    Attributes:
+        domain: 领域标识 (如 coding / browser / data_analysis)
+        display_name: 可读名称
+        tools: 该领域的工具列表
+        outcome_spec: 结果判定规则
+        task_fields: 领域特有的任务字段 {字段名: 说明}
+        default_rubric_weights: 默认 rubric 权重覆盖
+    """
+
+    domain: str
+    display_name: str = ""
+    tools: list[ToolSpec] = Field(default_factory=list)
+    outcome_spec: OutcomeSpec = Field(default_factory=OutcomeSpec)
+    task_fields: dict[str, str] = Field(default_factory=dict)
+    default_rubric_weights: dict[str, float] = Field(default_factory=dict)
+
+
+# ============================================================
+# 内置领域 Profiles
+# ============================================================
+
+CODING_PROFILE = DomainProfile(
+    domain="coding",
+    display_name="Code Agent",
+    tools=[
+        ToolSpec(
+            name="read_file", category=ToolCategory.READ,
+            stateful_key="file_path",
+            aliases=["Read", "cat"],
+        ),
+        ToolSpec(
+            name="edit_file", category=ToolCategory.WRITE,
+            stateful_key="file_path",
+            aliases=["Edit", "sed", "write_file", "Write"],
+        ),
+        ToolSpec(
+            name="bash", category=ToolCategory.EXECUTE,
+            aliases=["Bash", "shell", "run"],
+        ),
+        ToolSpec(
+            name="grep", category=ToolCategory.SEARCH,
+            aliases=["Grep", "Glob", "find", "ls", "search"],
+        ),
+        ToolSpec(name="git", category=ToolCategory.EXECUTE),
+        ToolSpec(name="ipython", category=ToolCategory.EXECUTE),
+        ToolSpec(name="submit", category=ToolCategory.SUBMIT),
+        ToolSpec(name="finish", category=ToolCategory.SUBMIT),
+        ToolSpec(name="think", category=ToolCategory.THINK),
+    ],
+    outcome_spec=OutcomeSpec(
+        success_field="success",
+        score_field="tests_passed",
+        total_field="tests_total",
+    ),
+    task_fields={
+        "repo": "Git 仓库 (owner/repo)",
+        "base_commit": "基础 commit hash",
+        "test_command": "测试命令",
+        "language": "编程语言",
+    },
+)
+
+BROWSER_PROFILE = DomainProfile(
+    domain="browser",
+    display_name="Browser Agent",
+    tools=[
+        ToolSpec(
+            name="click", category=ToolCategory.WRITE,
+            stateful_key="element_id",
+            aliases=["tap"],
+        ),
+        ToolSpec(
+            name="type_text", category=ToolCategory.WRITE,
+            stateful_key="element_id",
+            aliases=["type", "fill", "input"],
+        ),
+        ToolSpec(
+            name="navigate", category=ToolCategory.NAVIGATE,
+            stateful_key="url",
+            aliases=["goto", "open_url"],
+        ),
+        ToolSpec(name="screenshot", category=ToolCategory.READ),
+        ToolSpec(
+            name="scroll", category=ToolCategory.NAVIGATE,
+            aliases=["scroll_up", "scroll_down"],
+        ),
+        ToolSpec(name="wait", category=ToolCategory.READ),
+        ToolSpec(name="extract_text", category=ToolCategory.READ),
+        ToolSpec(name="select", category=ToolCategory.WRITE),
+        ToolSpec(name="submit", category=ToolCategory.SUBMIT),
+    ],
+    outcome_spec=OutcomeSpec(success_field="success"),
+    task_fields={
+        "url": "目标 URL",
+        "expected_result": "预期结果描述",
+    },
+)
+
+GENERIC_PROFILE = DomainProfile(
+    domain="generic",
+    display_name="Generic Tool-Use Agent",
+    tools=[],
+    outcome_spec=OutcomeSpec(success_field="success"),
+)
+
+_BUILTIN_PROFILES: dict[str, DomainProfile] = {
+    "coding": CODING_PROFILE,
+    "browser": BROWSER_PROFILE,
+    "generic": GENERIC_PROFILE,
+}
+
+
+def get_domain_profile(domain: str) -> DomainProfile:
+    """获取内置领域 Profile.
+
+    Args:
+        domain: 领域标识 (coding / browser / generic)
+
+    Returns:
+        对应的 DomainProfile，未找到时返回 GENERIC_PROFILE
+    """
+    return _BUILTIN_PROFILES.get(domain, GENERIC_PROFILE)
+
+
+def load_domain_profile(path: str) -> DomainProfile:
+    """从 JSON 文件加载自定义 DomainProfile.
+
+    Args:
+        path: JSON 文件路径
+
+    Returns:
+        DomainProfile 实例
+    """
+    with open(path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+    return DomainProfile.model_validate(data)
+
+
+def list_domain_profiles() -> list[str]:
+    """列出所有内置领域名称."""
+    return list(_BUILTIN_PROFILES.keys())

knowlyr_core-0.1.0/src/knowlyrcore/env.py

@@ -0,0 +1,135 @@
+"""AgentEnv — Gymnasium 风格 Agent 环境协议.
+
+借鉴 Gymnasium Env + BrowserGym + AgentGym 的核心模式：
+- reset() → TimeStep
+- step(action) → TimeStep
+- close()
+- Wrapper 可组合
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from knowlyrcore.timestep import TimeStep
+
+
+class AgentEnv(ABC):
+    """Agent 环境协议.
+
+    所有环境（Docker 沙箱、浏览器、API mock 等）都实现此接口。
+    action 格式统一为 ``{"tool": "...", "params": {...}}``。
+
+    Usage::
+
+        env = SandboxEnv(config)
+        ts = env.reset(task=my_task)
+        while not ts.done:
+            action = agent.act(ts.observation)
+            ts = env.step(action)
+        env.close()
+    """
+
+    metadata: dict[str, Any] = {}
+    domain: str = "coding"
+
+    @abstractmethod
+    def reset(
+        self,
+        *,
+        task: Any | None = None,
+        seed: int | None = None,
+    ) -> TimeStep:
+        """重置环境到初始状态.
+
+        Args:
+            task: 任务信息 (TaskInfo 或兼容 dict)
+            seed: 随机种子（用于可复现性）
+
+        Returns:
+            初始 TimeStep
+        """
+        ...
+
+    @abstractmethod
+    def step(self, action: dict[str, Any]) -> TimeStep:
+        """执行一步动作.
+
+        Args:
+            action: 动作字典，格式 {"tool": "...", "params": {...}}
+
+        Returns:
+            执行后的 TimeStep
+        """
+        ...
+
+    def close(self) -> None:
+        """清理资源（默认空实现）."""
+
+    @property
+    def available_tools(self) -> list[str]:
+        """当前可用的工具/动作名列表."""
+        return []
+
+    @property
+    def unwrapped(self) -> AgentEnv:
+        """返回最内层非 Wrapper 环境."""
+        return self
+
+    def __enter__(self) -> AgentEnv:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__} domain={self.domain!r}>"
+
+
+class EnvWrapper(AgentEnv):
+    """环境包装器基类 — 对应 gymnasium.Wrapper.
+
+    透传所有方法到内部环境，子类只需覆盖想要修改的方法。
+
+    Usage::
+
+        class MyWrapper(EnvWrapper):
+            def step(self, action):
+                ts = self.env.step(action)
+                ts.reward = compute_reward(ts)
+                return ts
+    """
+
+    def __init__(self, env: AgentEnv):
+        self.env = env
+
+    def reset(self, **kwargs: Any) -> TimeStep:
+        """透传 reset."""
+        return self.env.reset(**kwargs)
+
+    def step(self, action: dict[str, Any]) -> TimeStep:
+        """透传 step."""
+        return self.env.step(action)
+
+    def close(self) -> None:
+        """透传 close."""
+        self.env.close()
+
+    @property
+    def available_tools(self) -> list[str]:
+        """透传 available_tools."""
+        return self.env.available_tools
+
+    @property
+    def unwrapped(self) -> AgentEnv:
+        """递归返回最内层环境."""
+        return self.env.unwrapped
+
+    @property
+    def domain(self) -> str:  # type: ignore[override]
+        """透传 domain."""
+        return self.env.domain
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__}({self.env!r})>"

knowlyr_core-0.1.0/src/knowlyrcore/models.py

@@ -0,0 +1,59 @@
+"""共享数据模型 — ToolResult / TaskInfo."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ToolResult(BaseModel):
+    """工具执行结果.
+
+    Attributes:
+        output: 标准输出内容
+        exit_code: 退出码 (0 表示成功)
+        error: 错误信息 (如果有)
+    """
+
+    output: str = ""
+    exit_code: int = 0
+    error: str | None = None
+
+    @property
+    def success(self) -> bool:
+        """执行是否成功."""
+        return self.exit_code == 0 and self.error is None
+
+
+class TaskInfo(BaseModel):
+    """任务信息.
+
+    描述一个待执行的任务，支持任意领域。coding 特有字段（repo/base_commit 等）
+    保留供向后兼容，非 coding 领域可忽略。
+
+    Attributes:
+        task_id: 任务唯一标识
+        description: 任务描述
+        type: 任务类型 (如 bug_fix, feature, qa_check)
+        language: 编程语言 (coding 领域)
+        difficulty: 难度等级 (easy / medium / hard)
+        repo: 目标仓库 (coding 领域, 如 "owner/repo")
+        base_commit: 基础 commit hash (coding 领域)
+        test_command: 测试命令 (coding 领域)
+        domain: 所属领域 (coding / browser / generic / 自定义)
+        success_criteria: 成功判定描述 (领域无关)
+        metadata: 额外元数据
+    """
+
+    task_id: str = ""
+    description: str = ""
+    type: str = ""
+    language: str = ""
+    difficulty: str = ""
+    repo: str = ""
+    base_commit: str = ""
+    test_command: str = ""
+    domain: str = ""
+    success_criteria: str = ""
+    metadata: dict[str, Any] = Field(default_factory=dict)

knowlyr_core-0.1.0/src/knowlyrcore/registry.py

@@ -0,0 +1,117 @@
+"""环境注册表 — knowlyr.make() 发现机制.
+
+借鉴 gymnasium.register() / gymnasium.make() 模式，
+命名规范沿用 "namespace/env-name" 格式。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from knowlyrcore.env import AgentEnv
+
+
+@dataclass
+class EnvSpec:
+    """环境规格 — 对应 gymnasium.EnvSpec.
+
+    Attributes:
+        id: 环境标识 (如 "knowlyr/sandbox", "swebench/django-11099")
+        env_cls: 环境类
+        kwargs: 默认构造参数
+        domain: 领域标识
+        description: 环境描述
+    """
+
+    id: str
+    env_cls: type[AgentEnv]
+    kwargs: dict[str, Any] = field(default_factory=dict)
+    domain: str = "coding"
+    description: str = ""
+
+
+_REGISTRY: dict[str, EnvSpec] = {}
+
+
+def register(
+    id: str,
+    env_cls: type[AgentEnv],
+    *,
+    domain: str = "coding",
+    description: str = "",
+    **kwargs: Any,
+) -> None:
+    """注册一个环境.
+
+    Args:
+        id: 环境标识 (如 "knowlyr/sandbox")
+        env_cls: 环境类（必须继承 AgentEnv）
+        domain: 领域标识
+        description: 环境描述
+        **kwargs: 默认构造参数
+
+    Raises:
+        ValueError: 环境 ID 已注册
+    """
+    if id in _REGISTRY:
+        raise ValueError(f"环境已注册: {id!r}")
+    _REGISTRY[id] = EnvSpec(
+        id=id,
+        env_cls=env_cls,
+        kwargs=kwargs,
+        domain=domain,
+        description=description,
+    )
+
+
+def make(id: str, **override_kwargs: Any) -> AgentEnv:
+    """创建环境实例 — 对应 gymnasium.make().
+
+    Args:
+        id: 环境标识
+        **override_kwargs: 覆盖默认构造参数
+
+    Returns:
+        AgentEnv 实例
+
+    Raises:
+        KeyError: 环境未注册
+    """
+    if id not in _REGISTRY:
+        available = ", ".join(sorted(_REGISTRY.keys())) or "(空)"
+        raise KeyError(f"未注册的环境: {id!r}。可用: {available}")
+    env_spec = _REGISTRY[id]
+    merged_kwargs = {**env_spec.kwargs, **override_kwargs}
+    return env_spec.env_cls(**merged_kwargs)
+
+
+def list_envs(domain: str | None = None) -> list[str]:
+    """列出已注册的环境 ID.
+
+    Args:
+        domain: 按领域过滤（None 返回全部）
+
+    Returns:
+        环境 ID 列表
+    """
+    if domain is None:
+        return sorted(_REGISTRY.keys())
+    return sorted(k for k, v in _REGISTRY.items() if v.domain == domain)
+
+
+def spec(id: str) -> EnvSpec | None:
+    """获取环境规格.
+
+    Args:
+        id: 环境标识
+
+    Returns:
+        EnvSpec 或 None
+    """
+    return _REGISTRY.get(id)
+
+
+def _clear_registry() -> None:
+    """清空注册表（仅用于测试）."""
+    _REGISTRY.clear()