跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://simplellmfunc.cn/llms.txt

Use this file to discover all available pages before exploring further.

​
运行时原语

Primitives 是可以在 execute_code（PyRepl）内部通过 runtime.<namespace>.<name>(...) 调用的函数。它们让工具能够在不打破工具边界的情况下访问 Agent 级别的能力。

​
概念

概念含义
PrimitivePack一组相关原语及其后端的命名集合
RuntimePrimitiveBackendPrimitivePack 所包装的有状态对象（例如 SelfReference）
@primitive将函数注册为可调用原语的装饰器
PrimitiveSpec暴露给模型的契约（名称、描述、参数、最佳实践）
PrimitiveCallContext传递给原语处理函数的运行时上下文

​
内置原语：SelfRef Pack

框架内置了一个 Pack —— selfref —— 提供 6 个原语： 
runtime.selfref.context.inspect()
runtime.selfref.context.remember(text)
runtime.selfref.context.forget(experience_id)
runtime.selfref.context.compact(goal, instruction, ...)
runtime.selfref.fork.spawn(task, instruction, ...)
runtime.selfref.fork.gather_all(include_history=False)

​
创建自定义 Pack

​
1. 定义 Backend

from SimpleLLMFunc.runtime import RuntimePrimitiveBackend


class MetricsBackend(RuntimePrimitiveBackend):
    def __init__(self):
        self.counters: dict[str, int] = {}

    def increment(self, name: str, amount: int = 1) -> int:
        self.counters[name] = self.counters.get(name, 0) + amount
        return self.counters[name]

    def get_all(self) -> dict[str, int]:
        return dict(self.counters)

​
2. 定义 Primitives

from SimpleLLMFunc.runtime import primitive, PrimitiveCallContext


@primitive
async def increment_counter(
    ctx: PrimitiveCallContext,
    name: str,
    amount: int = 1,
) -> dict:
    """
    Increment a named counter and return its new value.

    Args:
        name: Counter name.
        amount: How much to add. Default 1.

    Returns:
        Dict with counter name and new value.

    Best Practices:
        - Use descriptive counter names (e.g., "files_processed", "errors_found").
        - Use this to track progress across tool calls.
    """
    backend: MetricsBackend = ctx.backend
    new_value = backend.increment(name, amount)
    return {"name": name, "value": new_value}


@primitive
async def get_metrics(ctx: PrimitiveCallContext) -> dict:
    """
    Get all current counter values.

    Returns:
        Dict of all counter names to their current values.

    Best Practices:
        - Call this to report progress summaries.
        - Useful before context compaction to record final metrics.
    """
    backend: MetricsBackend = ctx.backend
    return backend.get_all()
Primitive 的 docstring 必须包含 Best Practices 部分。缺少该部分将导致注册失败。

​
3. 构建 Pack

from SimpleLLMFunc.runtime import PrimitivePack

metrics_pack = PrimitivePack(
    namespace="metrics",
    backend=MetricsBackend(),
    primitives=[increment_counter, get_metrics],
    guide={
        "namespace": "metrics",
        "overview": "Track numeric counters across tool calls.",
        "best_practices": {
            "when_to_use": "To track progress, count occurrences, or measure work done.",
            "pattern": "Increment during work, get_metrics at milestones.",
        },
    },
)

​
4. 安装到 PyRepl

from SimpleLLMFunc.builtin import PyRepl

repl = PyRepl()
repl.install_primitive_pack(metrics_pack)
现在模型可以调用： 
runtime.metrics.increment_counter("files_read")
runtime.metrics.get_metrics()

​
可发现性

模型通过内置的元原语来发现可用的 Primitives： 
runtime.list_primitives()              # 所有可用的原语名称
runtime.get_primitive_spec("metrics.increment_counter")  # 完整契约
runtime.list_backends()                # 已安装的 backend packs
Spec 中包含参数描述、返回类型和最佳实践——足以让模型在无需预训练的情况下正确使用原语。

​
PrimitiveCallContext

每个原语处理函数都会接收一个上下文对象： 
@dataclass
class PrimitiveCallContext:
    backend: RuntimePrimitiveBackend   # Pack 的 backend 实例
    fork_context: Optional[ForkContext]  # Fork 信息（如果在 fork 内部）
    event_emitter: ToolEventEmitter    # 发送自定义事件
使用 ctx.event_emitter 可以在长时间运行的原语中流式推送进度。 → API 参考：Runtime