yera-labs.io

Search and read the Yera 0.5.0 documentation. Use search_docs to find pages, get_page to read one in full and list_pages to browse a section. # How Yera fits together Yera apps are plain Python functions, written with `import yera as yr`. Install it with `pip install yera` (or `uv add yera`), then run `yera setup` to connect model providers. Read this before the reference pages: it is the model they all assume. It isn't a page on the site, so don't cite it; cite the pages you open instead. - **Apps.** `@yr.app(name=..., sys_prompt=...)` turns a function into an app. Each run of an app has its own conversation (its workspace: messages and variables) and system prompt, and talks to a model through an LLM context. `yera run app.py` serves it in the browser UI. Calling one app from another runs it as a nested app (a separate agent) with a fresh conversation. Data passes as typed arguments and return values (e.g. `return yr.response(topic)`); the caller doesn't see the nested app's conversation, so insert what it needs. - **Models.** `yr.llm` is the atlas of models configured in the user's profile, so which models exist depends on their setup: `print(yr.llm)` shows them and the default. An app uses the default unless given one: `@yr.app(llm=yr.llm["provider.model"]())`, with a name from `print(yr.llm)` (attribute access works too, dashes becoming underscores), so each nested app can run a different model. Don't assume a model name: use a placeholder and tell the user to pick one from their own list. `llm=yr.llm.none()` is only for an app that never calls the model itself: not even `yr.select` or `yr.condition`. - **LLM contexts.** An LLM context is which model the model calls go to; the app holds the conversation. Inside one app, `with yr.llm["provider.model"]():` switches model for the calls in the block and continues the same conversation (the app's workspace). Contexts stack: when the block ends, the previous model is active again. Only a nested app starts a fresh conversation. - **The conversation.** `yr.chat()` yields each user message but doesn't call the model. `yr.insert(text)` adds a message, `yr.gen(instruction=...)` generates from the conversation so far, and `yr.response(prompt)` does both at once. Both stream their reply to the user as they go and return its text, so don't show the returned text again with `yr.markdown()`. - **Decisions.** `yr.select("a", "b", instruction=...)` lets the model pick a branch and `yr.condition(instruction)` returns a bool. Python's own `if` and `match` then run the chosen path. - **Tools are called explicitly.** `@yr.tool` wraps a typed Python function. Yera never picks tools on its own, and `yr.response()` and `yr.gen()` take no `tools=`. App code calls `my_tool(args)` when Python holds the arguments, or `my_tool.invoke(instruction=...)` to have the model fill them from the conversation. Either way the result goes into the conversation, so call `yr.gen()` next. MCP tools (`yr.mcp_tools["server.tool"]`) work the same way. - **Structured data.** Subclass `yr.Struct` to declare typed fields. Then `.fill(instruction=...)` has the model produce one, and `.form("label")` asks the user to fill it in as a form (defaults become pre-filled values). - **Input and output.** Input functions ask the user for text, choices, dates and forms. Output functions show Markdown, tables, charts and images. Each one has its own reference page. A conversational app that uses a tool: ```python import yera as yr @yr.tool def get_weather(city: str) -> dict: """Current weather for a city.""" ... @yr.app(name="Weather Bot", sys_prompt="You answer questions about the weather.") def weather_bot() -> None: for prompt in yr.chat(): yr.insert(prompt) if yr.condition("Does the latest message ask about the weather?"): get_weather.invoke(instruction="Get the weather for the city mentioned.") yr.gen() ``` ## Finding your way around these docs - Every `yr` function is listed at the end of this overview with its signature. Open its page (`/docs/yera/reference/api/<name>/`) for argument details and examples. - Tutorials build things step by step; the API reference documents each `yr.*` function; the CLI reference covers each `yera` command; the implementation reference documents internals and classes such as `DecoratedTool`. - Every page ends with links: the pages in its section, "Used in" (tutorials that use an API function), "See also" (related API pages and classes), and "Up". - Search with short keyword queries for what you need (`table`, `yera run`, `structured extraction`), and open the best result before searching again. ## Every `yr` function - `yr.app(fn: Callable | None = None, name: str | None = None, description: str | None = None, llm: LLMContext | None = None, sys_prompt: str | None = None) → AppFunctionWrapper | Callable[[Callable], AppFunctionWrapper]`: Decorator that turns a Python function into a Yera app. - `yr.exit(exit_code: int, reason: str, return_value: object, error_cause: ErrorCause | None = None) → None`: End the current app run. - `yr.quit() → None`: End the current app run as a user-initiated quit. - `yr.session_title(title: str) → None`: Set the title associated with the current session. - `yr.tool(fn: Callable | None = None, creds: str | list[str] | None = None, insert_result: bool = True) → DecoratedTool | Callable[[Callable], DecoratedTool]`: Decorate a Python function as a Yera tool. - `yr.tool_creds() → ToolCreds`: Return the active tool's credentials. - `yr.workspace`: The active app's workspace. - `yr.chat(stop_str: str = '/quit') → Generator[str]`: Yield user prompts until one starts with stop_str. - `yr.gen(on_wire: bool = True, instruction: str | None = None, **kwargs) → str`: Generate a response from the active LLM with optional instruction and visibility control. - `yr.insert(prompt: str) → None`: Insert a prompt into the active LLM context. - `yr.response(prompt: str, **kwargs) → str`: Send a prompt to the active LLM and return its text response. - `yr.Struct`: Base class for structured-generation specs. - `yr.sys_prompt(prompt: str) → None`: Append a line to the active LLM context's system prompt. - `yr.llm`: The configured LLM atlas, loaded lazily on first access. - `yr.buttons(options: list[str], label: str | None = None) → str`: Present the user with a set of buttons and return their selection. - `yr.confirm(label: str | None = None, true_option: str = 'Yes', false_option: str = 'No') → bool`: Present the user with a binary choice and return True/False. - `yr.date_picker(label: str, default_date: date | str | None = None) → date`: Present the user with a date picker. - `yr.slider(min_value: float, max_value: float, label: str, default_value: float | None = None) → float`: Present the user with a slider over a numeric range. - `yr.text_input(message: str | None = None) → str`: Prompt the user for free-form text input. - `yr.tree_selector(tree: TreeSelectorSource, label: str | None = None, min_selections: int = 1, max_selections: int | None = None) → list[str]`: Present a nested tree and return the selected leaf values. - `yr.bar_chart(data: object, x: str | None = None, y: str | Sequence[str] | None = None, colour: str | Sequence[str] | None = None, horizontal: bool = False, stack: bool = True) → None`: Render a bar chart. - `yr.image(content: bytes, media_type: ImageMediaType = 'image/png', alt: str | None = None) → None`: Render an image from image-file bytes. - `yr.line_chart(data: object, x: str | None = None, y: str | Sequence[str] | None = None, colour: str | Sequence[str] | None = None) → None`: Render a line chart. - `yr.markdown(content: str) → None`: Render a markdown block. - `yr.spinner(message: str = 'Working', glyph: str = 'run', colour: NamedColour = 'orange', end_message: str = 'Done', end_glyph: str = 'check', end_colour: NamedColour = 'green') → SpinnerStream`: Show a configurable spinner while a block of work runs. - `yr.table(data: object = None, border: bool | Literal['horizontal'] = True) → TableStream`: Render a table. - `yr.condition(instruction: str, on_wire: bool = False, **kwargs) → bool`: Use the active LLM to evaluate a boolean condition. - `yr.mcp_tools`: MCP tools selected by the active profile, loaded lazily. - `yr.option(label: str, description: str | None = None) → Option`: Create an Option instance. - `yr.result`: Result block implementation. - `yr.section(title: str, summary: str | None = None, auto_collapse: bool = True, glyph: str = 'thread', colour: NamedColour | None = None) → Section`: Group output blocks into a mutable, collapsible section. - `yr.select(*options, instruction: str | None = None, name: str = 'Selection', on_wire: bool = False, **kwargs) → str`: Use the active LLM to choose between a set of options.