from SimpleLLMFunc.builtin import SelfReference

SelfReference()

# Automatic (recommended)
@llm_chat(llm_interface=llm, self_reference_key="agent_main", ...)
async def agent(...):
    ...

# Explicit backend
selfref = SelfReference()
selfref.bind_history("my_key", initial_history)

@llm_chat(llm_interface=llm, self_reference=selfref, self_reference_key="my_key", ...)
async def agent(...):
    ...

# Context
runtime.selfref.context.inspect() -> dict
runtime.selfref.context.remember(text: str) -> dict  # {id, text}
runtime.selfref.context.forget(experience_id: str) -> bool
runtime.selfref.context.compact(
    goal: str,
    instruction: str,
    discoveries: list[str],
    completed: list[str],
    current_status: str,
    likely_next_work: str,
    relevant_files_directories: list[str],
    remember: list[str] = [],
) -> dict  # {assistant_message, ...}

# Fork
runtime.selfref.fork.spawn(
    task: str,
    instruction: str,
    ...
) -> dict  # {fork_id, status}
runtime.selfref.fork.gather_all(include_history: bool = False) -> dict  # {fork_id: ForkResult}

from SimpleLLMFunc.builtin import PyRepl

PyRepl(working_directory: Optional[Path | str] = None)

async def execute_code(code: str, event_emitter=None) -> dict:
    """Run Python code in the persistent REPL."""

{
    "stdout": str,          # Captured stdout
    "stderr": str,          # Captured stderr
    "return_value": str,    # Repr of last expression (or None)
    "artifacts": list,      # 直接调用 PyRepl.execute 时捕获到的图片产物
    "error": str | None,    # Error message if failed
    "execution_time_ms": float,
}

async def reset_repl() -> str:
    """Clear REPL variables. Preserves runtime backends."""

from SimpleLLMFunc.builtin import PyRepl

repl = PyRepl(working_directory="/path/to/project")

@llm_chat(llm_interface=llm, toolkit=repl.toolset, stream=True)
async def code_agent(message: str, history: list | None = None):
    """Execute Python to solve problems."""
    pass

from SimpleLLMFunc.builtin import FileToolset

FileToolset(workspace: Path | str)

async def read_file(path: str, start_line: int = None, end_line: int = None) -> str

async def read_image(path: str) -> ImgPath

async def grep(pattern: str, path_pattern: str) -> str

async def sed(path: str, start_line: int, end_line: int, pattern_to_be_replaced: str, new_string: str) -> str

async def echo_into(path: str, content: str) -> str

from SimpleLLMFunc.builtin import FileToolset

files = FileToolset("/path/to/workspace")

@llm_chat(llm_interface=llm, toolkit=files.toolset, stream=True)
async def file_agent(message: str, history: list | None = None):
    """An agent that can read and edit files in the workspace."""
    pass