Metadata-Version: 2.5
Name: yera
Version: 0.11.1
Summary: An easier, safer way to write AI apps
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Requires-Python: >=3.11
Requires-Dist: anthropic>=0.76.0
Requires-Dist: anyio>=4.14.2
Requires-Dist: aws-bedrock-token-generator>=1.1.0
Requires-Dist: azure-identity>=1.25.3
Requires-Dist: azure-mgmt-cognitiveservices>=14.1.0
Requires-Dist: azure-mgmt-resource-subscriptions>=1.0.0b1
Requires-Dist: azure-mgmt-resource>=25.0.0
Requires-Dist: boto3>=1.42.45
Requires-Dist: botocore>=1.42.46
Requires-Dist: cloudpickle>=3.1.2
Requires-Dist: cycler>=0.12.1
Requires-Dist: cyclopts>=4.22.4
Requires-Dist: fastapi>=0.104.0
Requires-Dist: filelock>=4.2.1
Requires-Dist: gguf>=0.17.1
Requires-Dist: google-genai>=2.20.0
Requires-Dist: httpx2>=2.12.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: jsonschema[format-nongpl]>=4.26.0
Requires-Dist: markdown>=3.10.2
Requires-Dist: matplotlib>=3.10.8
Requires-Dist: mcp-types<3,>=2
Requires-Dist: mcp<3,>=2
Requires-Dist: mistralai>=1.10.0
Requires-Dist: mistune>=3.2.0
Requires-Dist: numpy>=2.2.6
Requires-Dist: openai>=2.53.0
Requires-Dist: openrouter>=1.1.91
Requires-Dist: packaging>=24.0
Requires-Dist: pandas-stubs>=2.3.3.251219
Requires-Dist: pandas>=2.2.3
Requires-Dist: pillow>=12.2.0
Requires-Dist: prompt-toolkit>=3.0.52
Requires-Dist: pyarrow>=23.0.1
Requires-Dist: pydantic>=2.12
Requires-Dist: pylatexenc>=2.10
Requires-Dist: python-multipart>=0.0.32
Requires-Dist: pywin32>=312; sys_platform == 'win32'
Requires-Dist: questionary>=2.1.1
Requires-Dist: rich>=13.0.0
Requires-Dist: tomlkit>=0.13.0
Requires-Dist: typing-extensions>=4.16.0
Requires-Dist: uvicorn>=0.24.0
Provides-Extra: llama-cpp
Requires-Dist: llama-cpp-python>=0.3.34; extra == 'llama-cpp'
Provides-Extra: ollama
Requires-Dist: ollama>=0.6.1; extra == 'ollama'
Description-Content-Type: text/markdown

<p align="center">
  <a href="https://yera-labs.io/yera/">
    <img
      src="docs/assets/brand/yera-wordmark.svg"
      alt="Yera Labs"
      width="260"
    >
  </a>
</p>

<p align="center">
  Yera makes it easy to build end-to-end AI apps in Python.<br>
  Orchestrate model invocations, UI elements and more using syntax you already know.
</p>

<p align="center">
  <a href="https://yera-labs.io/docs/">Documentation</a> ·
  <a href="https://yera-labs.io/docs/yera/reference/api/">API reference</a> ·
  <a href="https://yera-labs.io/docs/yera/reference/cli/">CLI reference</a> ·
  <a href="CONTRIBUTING.md">Contributing</a>
</p>

> [!IMPORTANT]
> Yera is prerelease software. Its APIs and configuration may change before 1.0.

## Start Here

Getting started with Yera is easy: there's a single installation from PyPI, and then a
guided setup process that will get you configured and ready to build.

### Using `uv`

We recommend using [uv](https://docs.astral.sh/uv/) to manage your Python environment, but it's not required.
You can do a normal pip install and expect everything to work the same.

#### Install

Assuming you are in a directory where `uv init` has been run, just do

```
uv add yera
```

to install. This does not include `ollama` or `llama-cpp-python` dependencies by default,
but they are supported as extras. You can also just install them yourself.

#### Get onboarded

Once the library is installed you can then run

```
uv run yera hello
```

This will bring up a Yera browser window with the hello app running inside it.

Hello will take you through

- Setting up your model providers (i.e. OpenAI, Anthropic etc.), find the models you have available for them and then load it all into config.
- Choosing your default model from the configured set.
- Configuring the MCP connections you want to use.

After these hello can (if you choose) hand you over to yera guide, a chatbot that can query Yera's docs
and help you understand how to use Yera running on your default model choice.

### Using `pip`

With pip you simply run

```
pip install yera
yera hello
```

and then the rest of the process is the same.

### Optional: Connect the Docs MCP

To really hit the ground running [add the Yera docs MCP](https://yera-labs.io/docs/yera/how-to-guides/docs-in-your-ai-tools/) to your agentic coding app.

## Build and Run Your First App

To build your first chatbot create a file called `app.py` and add the following code inside.

```python
import yera as yr


@yr.app
def chatbot() -> None:
    for msg in yr.chat():
        yr.response(msg)
```

After that, run with

```
uv run yera run app.py
```

### What You Just Ran

This is one of the simplest Yera applications you can write, and it demonstrates a few important components

- `import yera as yr` - Yera is designed to keep it simple: everything can be used from a single import.
- `@yr.app` - In Yera python functions are promoted to apps using a decorator. To run an app you can call it, to run an app within an app just call it in the function body. You can build up multi-agent system with nested calls like this.
- `yr.response` - This is an LLM-powered function that takes a prompt and returns a response. Functions like these are aware of the app they are in and the model context they should use.

- `yr.chat` - this is a chat loop. It will iteratively ask the user for input and yield it.

### Other ways to run

You do not have to run apps in the browser. Since they're just python functions you can run them wherever you can call them. You can run the above app in jupyter by simply calling it. To run in a plain python script you can also just call the chatbot function, but it will need to be behind a main guard due to how the Yera runtime handles processes. Add

```
if __name__ == "__main__":
    chatbot()
```

to the bottom of your script in that case.

## Why Yera?

Yera is designed to bring all the components to build sophisticated AI apps together in one natural interface familiar to you and your coding agent.

- build the whole thing in python (`if`, `match`, etc.)
- separate applications from models, stay provider-neutral
- connect your existing tools via MCP, or python
- build a ui by calling python functions - no frontend experience needed
- keep a trace of everything that happened in your application for observability and governance. Visualise it in the browser UI.
- access your Yera apps running on your server from anywhere and share them with others via [Yera Link](https://yera-labs.io/yera-link/) (coming soon).

Plus, much more to come such as easy hosting / deployment, full execution audit trails, static analysis of data flows in your apps, and batch jobs / pipelines.

## Core Concepts

### Apps

A Yera app is a self-contained unit of AI-powered functionality, written as a Python function.
It can combine model operations, tools, user interface elements, control flow and other Yera apps into one reusable flow.

You build these apps by decorating ordinary python functions with `@yr.app`, you run them by calling them like any other function.
Calling one app from another starts a nested app with its own conversation and model context.

### Models, Contexts and Generation

In Yera, models are separated from application logic. They are a component of the software and invoked with particular primitives that live under the top-level import. The model they actually use is set by the active context.

```python
@yr.app(llm=yr.llm.model1())
def demo():
    yr.response("prompt 1")  # goes to model1

    with yr.llm.model2():
        yr.response("prompt 2")  # goes to model2

    yr.response("prompt 3")  # goes to model1
```

Model contexts can be set explicitly by using them using them as a context manager via the `with` keyword. In addition to this apps will use your default model automatically if no other is specified.

```python
@yr.app
def demo():
    yr.response("What's the capital of France?")
```

### Inputs and Outputs

Yera turns Python function calls into user interaction. Input functions collect
text, choices, dates, numbers and structured forms, while output functions
present Markdown, tables, charts, images and other interface elements.

The runtime sends those interactions through the active presentation layer, so
the same app can run in Yera's browser UI, jupyter or in the terminal without a separate
frontend implementation.

### Structured Data

Define and validate data structures as `yr.Struct` subclasses using typed python fields.
Call `.fill()` to create an instance using the current LLM, or `.form()` to present it to the user as a form input widget.

```python
class Point(yr.Struct):
    x: str
    y: str

p1 = Point.fill()
p2 = Point.form()
```

This gives model-generated data and user input the same explicit, validated
shape before the rest of the application uses it.

### Control Flow

Yera contains two functions for model-driven control flow: condition and select.

`yr.condition`

```python
if yr.condition("The user is asking about the weather."):
    forecast.invoke()
else:
    yr.gen()
```

`yr.select`

```python
match yr.select("billing", "tech", "sales"):
    case "billing":
        refund.invoke()
    case "tech":
        diagnose.invoke()
    case "sales":
        yr.gen()
```

You can use the output of these in normal `if`, `match`, loops and function calls.

### Tools

A Yera tool is a function-shaped capability that an app can call. It has a name, a description, typed inputs and a result, together with an interface that integrates its execution into the Yera runtime.

Tools can have one of two origins: either a python function decorated with `@yr.tool` or an MCP operation accessed through `yr.mcp`. In either case application code uses a callable object with extra methods.

Call a tool normally when your app already has the right values

```python
weather = get_weather(city="London")
```

Use `.invoke()` when you want the active LLM to derive the model arguments from the current context and call the function

```python
weather = get_weather.invoke(
    instruction="Get the weather for the city the user mentioned."
)
```

When a tool runs inside an app, Yera wraps the call with runtime behaviour: it records a traceable tool operation, handles its presentation and lifecycle, and makes its result available to subsequent model operations. The trace records safe operational metadata rather than tool arguments or results.

### Sessions and Events

During app execution, Yera produces an ordered stream of events. Output events describe what should be shown to the user, while input events carry the user’s responses back to the waiting app.

The runtime also emits logging events for app invocations, model requests, tool calls, session lifecycle changes and other useful operational metadata.

Together, these events form a record of the session. Separating app execution from its presentation allows the same app to work across different interfaces. When an app runs through the Yera browser server, the record is stored and used to reconstruct the session and display its activity trace.
Everything a Yera app shows (and every runtime operation Yera instruments) becomes part of this record.

## Learn Yera

- **[Quickstart](https://yera-labs.io/docs/yera/tutorials/quickstart/)** —
  install Yera, configure a model and build your first app.
- **[Tutorials](https://yera-labs.io/docs/yera/tutorials/)** —
  learn Yera progressively through complete working examples.
- **[How-to guides](https://yera-labs.io/docs/yera/how-to-guides/)** —
  find focused instructions for particular tasks and integrations.
- **[Examples](examples/)** —
  explore small Yera apps that you can run and modify.
- **[API reference](https://yera-labs.io/docs/yera/reference/api/)** and
  **[CLI reference](https://yera-labs.io/docs/yera/reference/cli/)** —
  look up individual functions, types and commands.
- **Yera Guide** — run `yera guide` for an interactive assistant that can search
  the Yera documentation using your configured model.

## Support and Project Status

Yera is prerelease and under active development. It supports Python 3.11 onwards.
APIs, config etc. may change before version 1.0.

Please report bugs and feature requests through [GitHub Issues](https://github.com/yera-labs/Yera/issues).
When reporting a problem please include your yera version, python version, operating system and a small reproducible example.
Make sure you remove any creds or other sensitive data beforehand.

## Contributing

Contributions to Yera are welcome, including bug fixes, documentation,
integrations and examples. See [CONTRIBUTING.md](CONTRIBUTING.md) for development
setup, project checks and pull request guidance.

## License

Yera Core is licensed under the [Apache License 2.0](LICENSE).
