运行时 API 参考
PrimitivePack
from SimpleLLMFunc.runtime import PrimitivePack
@dataclass
class PrimitivePack:
namespace: str # e.g., "selfref", "metrics"
backend: RuntimePrimitiveBackend # Stateful backend instance
primitives: List[PrimitiveHandler] # Registered primitive functions
guide: Optional[Dict[str, Any]] = None # Namespace documentation
示例
from SimpleLLMFunc.runtime import PrimitivePack, RuntimePrimitiveBackend, primitive
class MyBackend(RuntimePrimitiveBackend):
pass
@primitive
async def my_action(ctx: PrimitiveCallContext, arg: str) -> dict:
"""Do something.
Args:
arg: Input argument.
Returns:
Result dict.
Best Practices:
- Use for X.
"""
return {"result": arg}
pack = PrimitivePack(
namespace="myns",
backend=MyBackend(),
primitives=[my_action],
guide={"namespace": "myns", "overview": "My custom primitives."},
)
@primitive
from SimpleLLMFunc.runtime import primitive
要求
- 第一个参数必须是
ctx: PrimitiveCallContext - 文档字符串必须包含
Best Practices部分 - 必须是
async def
@primitive
async def my_primitive(ctx: PrimitiveCallContext, param: str) -> dict:
"""Description.
Args:
param: Description.
Returns:
Result.
Best Practices:
- When to use this primitive.
"""
return {"value": param}
PrimitiveCallContext
from SimpleLLMFunc.runtime import PrimitiveCallContext
@dataclass
class PrimitiveCallContext:
backend: RuntimePrimitiveBackend # The pack's backend
fork_context: Optional[ForkContext] # Fork info if inside a fork
event_emitter: ToolEventEmitter # For emitting custom events
ForkContext
from SimpleLLMFunc.runtime import ForkContext
@dataclass
class ForkContext:
parent_pack_name: str
backend_name: str
child_fork_id: str | None = None
source_memory_key: str | None = None
metadata: dict[str, Any] | None = None
PrimitiveSpec
from SimpleLLMFunc.runtime import PrimitiveSpec
@dataclass
class PrimitiveSpec:
name: str # Full qualified name (e.g., "selfref.context.remember")
description: str # What it does
parameters: List[PrimitiveParameterSpec] # Parameter descriptions
returns: str # Return type description
best_practices: List[str] # Usage guidance
PrimitiveParameterSpec
@dataclass
class PrimitiveParameterSpec:
name: str
type: str
description: str
required: bool = True
default: Optional[Any] = None
PrimitiveRegistry
from SimpleLLMFunc.runtime import PrimitiveRegistry
关键方法
| 方法 | 描述 |
|---|---|
install_pack(pack) | 注册一个 PrimitivePack |
call(name, **kwargs) | 按限定名执行原语 |
list_primitives() | 列出所有已注册的原语名称 |
get_spec(name) | 获取某个原语的 PrimitiveSpec |
list_specs() | 获取所有规格 |
list_backends() | 列出已安装的后端包 |
RuntimePrimitiveBackend
from SimpleLLMFunc.runtime import RuntimePrimitiveBackend
class RuntimePrimitiveBackend:
"""Base class. Override to add state."""
pass
内置元原语
在 PyRepl 中始终可用，无需安装任何包：| 调用 | 返回值 |
|---|---|
runtime.list_primitives() | List[str] — 所有原语名称 |
runtime.list_primitive_specs() | List[PrimitiveSpec] — 所有规格 |
runtime.get_primitive_spec(name) | PrimitiveSpec — 单个规格 |
runtime.list_backends() | List[str] — 已安装的包 |
SelfRef 包注册
from SimpleLLMFunc.runtime import build_self_reference_pack, register_self_reference_primitives
# Build the pack
pack = build_self_reference_pack(selfref_backend)
# Or register directly into a PyRepl
register_self_reference_primitives(repl, selfref_backend)
runtime.selfref.context.* 和 runtime.selfref.fork.* 命名空间下提供原语。