Examples and Documents
Examples and documents provide controlled reference material for agent jobs. Loader helpers parse files; agent-facing tools list and show accessible entries.
| Symbol | Import path | Purpose | Stability |
|---|---|---|---|
Example | statek.executors.example | Parsed example data | Core helper |
Document | statek.document | Parsed document data | Core helper |
Topic | statek.document | Group of documents by topic | Core helper |
parse_example, load_examples, format_example, extract_example | statek.executors.example | Example helpers | Core helper |
parse_document, load_documents, find_topic, find_document | statek.document | Document helpers | Core helper |
list_of_examples, show_example | statek.agents.agent | Agent-facing example tools | Core system tools |
list_of_documents, show_document | statek.agents.agent | Agent-facing document tools | Core system tools |
Example
@dataclass
class Example:
example_metadata: dict
warmup_items: list[str]
example_items: list[str]| Member | Returns | Description |
|---|---|---|
difficulty | `TaskDifficulty | None` |
Example helpers
| Function | Signature | Returns | Errors |
|---|---|---|---|
extract_example | extract_example(job: Job, name: str) | Example | Propagates job/model access errors. |
format_example | format_example(example, chat_style, xml_tags=None, include_warmup=True, include_metadata=False) | str | None documented. |
parse_example | parse_example(example_md: str) | Example | ValueError for invalid content before the first code block. |
load_examples | load_examples(path: str) | list[Example] | ValueError if any .md file cannot be parsed. |
from statek.executors.example import load_examples
examples = load_examples("./examples")
first = examples[0]
print(first.example_metadata.get("name"))Document and Topic
@dataclass
class Document:
document_metadata: dict
body: list[str]
@dataclass
class Topic:
ord_no: int
topic: str
documents: list[Document]| Member | Returns | Description |
|---|---|---|
Document.match_audience(agent_name) | bool | Checks audience metadata; missing audience means all agents. |
Topic.count(agent_name) | int | Counts documents accessible to an agent. |
Document helpers
| Function | Signature | Returns | Errors |
|---|---|---|---|
parse_document | parse_document(document: str) | Document | ValueError if required headers are missing. |
load_documents | load_documents(path: str) | list[Topic] | ValueError if a document file cannot be parsed. |
find_topic | find_topic(key, agent_name, all_topics) | `Topic | None` |
find_document | find_document(key, agent_name, topic) | `Document | None` |
# ord_no: 0
# topic: Billing
# title: Refund policy
Refunds must be reviewed by support before approval.Agent-facing tools
| Function | Signature | Description |
|---|---|---|
list_of_examples | list_of_examples(start_index=0, max_count=10, **kwargs) | Lists configured examples for the current agent role. |
show_example | show_example(example_id, **kwargs) | Prints one configured example. |
list_of_documents | list_of_documents(topic=None, start_index=0, max_count=10, **kwargs) | Lists topics or documents accessible to the current agent role. |
show_document | show_document(key, topic=None, start_from=0, max_lines=40, **kwargs) | Prints a selected document or document slice. |