runa-ai 0.1.0__tar.gz

runa_ai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Khalil Brahim Benyous
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

runa_ai-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: runa-ai
+Version: 0.1.0
+Summary: The application framework for agentic AI.
+Author: Brahim Benyous
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: anthropic>=0.75.0
+Requires-Dist: graphviz>=0.21
+Requires-Dist: httpx2>=2.12.0
+Requires-Dist: mcp>=2.1.1
+Requires-Dist: mkdocs-material>=9.7.7
+Requires-Dist: pydantic>=2.9.0
+Requires-Dist: pypdf>=6.0.0
+Requires-Dist: sqlite-vec>=0.1.9
+Requires-Dist: asyncpg>=0.30.0 ; extra == 'postgres'
+Requires-Dist: pgvector>=0.3.6 ; extra == 'postgres'
+Requires-Dist: redis>=5.2.0 ; extra == 'redis'
+Requires-Dist: fastapi>=0.121.0 ; extra == 'ui'
+Requires-Dist: uvicorn>=0.38.0 ; extra == 'ui'
+Requires-Python: >=3.14
+Provides-Extra: postgres
+Provides-Extra: redis
+Provides-Extra: ui
+Description-Content-Type: text/markdown
+
+# Runa
+
+## What's Runa?
+
+Runa is an opinionated Python framework for agentic AI. Instead of a wide
+menu of configuration options, it gives you a small set of primitives,
+with clear conventions:
+
+- **Agents:** which are LLMs equipped with instructions and tools
+- **Tools:** the actions an agent can take in the outside world, described clearly enough that the agent knows when and how to use them.
+- **Guardrails:** checks that keep what goes into and comes out of an agent or tool within bounds.
+- **Delegation:** how agents hand off work to each other, either passing a task along completely or asking for help and getting an answer back.
+- **Context management:** what an agent remembers: session, memory, and domain knowledge.
+
+Observability and evaluation come built in, not bolted on: every run is
+traced automatically as a span tree, and evaluation grade
+correctness with plain assertions or judged, dataset-driven scoring.
+
+
+## Getting Started
+
+1. Install [uv](https://docs.astral.sh/uv/), then Runa:
+
+   ```bash
+   uv venv --python 3.14
+   source .venv/bin/activate
+   uv add git+https://github.com/benybrahim/runa.git
+   ```
+
+2. Scaffold a new application:
+
+   ```bash
+   runa new myapp
+   ```
+
+   where `myapp` is the application name.
+
+
+3. Change directory to `myapp`, generate an agent, and talk to it:
+
+   ```bash
+   cd myapp
+   runa generate agent AssistantAgent --model gpt-5.4-nano
+   runa chat assistant_agent
+   ```
+
+   Run any subcommand with `--help` for options.
+
+
+4. Fill in the API key for whichever model you use in `.env`, and you're
+   running.
+
+
+5. Follow the guides to keep building your application. You may find the following resources handy:
+   * [Getting Started with Runa](https://benybrahim.github.io/runa/getting_started/)
+   * [Runa Guides](https://benybrahim.github.io/runa/guides/)
+   * [CLI Reference](https://benybrahim.github.io/runa/cli/)
+
+## Read the Zen of Runa
+
+```bash
+python -c "from runa import this"
+```
+
+## Contributing
+
+We encourage you to contribute to Runa! Check out [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## License
+
+Runa is released under the [MIT License](./LICENSE).

runa_ai-0.1.0/README.md

@@ -0,0 +1,71 @@
+# Runa
+
+## What's Runa?
+
+Runa is an opinionated Python framework for agentic AI. Instead of a wide
+menu of configuration options, it gives you a small set of primitives,
+with clear conventions:
+
+- **Agents:** which are LLMs equipped with instructions and tools
+- **Tools:** the actions an agent can take in the outside world, described clearly enough that the agent knows when and how to use them.
+- **Guardrails:** checks that keep what goes into and comes out of an agent or tool within bounds.
+- **Delegation:** how agents hand off work to each other, either passing a task along completely or asking for help and getting an answer back.
+- **Context management:** what an agent remembers: session, memory, and domain knowledge.
+
+Observability and evaluation come built in, not bolted on: every run is
+traced automatically as a span tree, and evaluation grade
+correctness with plain assertions or judged, dataset-driven scoring.
+
+
+## Getting Started
+
+1. Install [uv](https://docs.astral.sh/uv/), then Runa:
+
+   ```bash
+   uv venv --python 3.14
+   source .venv/bin/activate
+   uv add git+https://github.com/benybrahim/runa.git
+   ```
+
+2. Scaffold a new application:
+
+   ```bash
+   runa new myapp
+   ```
+
+   where `myapp` is the application name.
+
+
+3. Change directory to `myapp`, generate an agent, and talk to it:
+
+   ```bash
+   cd myapp
+   runa generate agent AssistantAgent --model gpt-5.4-nano
+   runa chat assistant_agent
+   ```
+
+   Run any subcommand with `--help` for options.
+
+
+4. Fill in the API key for whichever model you use in `.env`, and you're
+   running.
+
+
+5. Follow the guides to keep building your application. You may find the following resources handy:
+   * [Getting Started with Runa](https://benybrahim.github.io/runa/getting_started/)
+   * [Runa Guides](https://benybrahim.github.io/runa/guides/)
+   * [CLI Reference](https://benybrahim.github.io/runa/cli/)
+
+## Read the Zen of Runa
+
+```bash
+python -c "from runa import this"
+```
+
+## Contributing
+
+We encourage you to contribute to Runa! Check out [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## License
+
+Runa is released under the [MIT License](./LICENSE).

runa_ai-0.1.0/pyproject.toml

@@ -0,0 +1,87 @@
+[project]
+name = "runa-ai"
+version = "0.1.0"
+description = "The application framework for agentic AI."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.14"
+dependencies = [
+    "anthropic>=0.75.0",
+    "graphviz>=0.21",
+    "httpx2>=2.12.0",
+    "mcp>=2.1.1",
+    "mkdocs-material>=9.7.7",
+    "pydantic>=2.9.0",
+    "pypdf>=6.0.0",
+    "sqlite-vec>=0.1.9",
+]
+
+[[project.authors]]
+name = "Brahim Benyous"
+
+[project.optional-dependencies]
+postgres = [
+    "asyncpg>=0.30.0",
+    "pgvector>=0.3.6",
+]
+redis = ["redis>=5.2.0"]
+ui = [
+    "fastapi>=0.121.0",
+    "uvicorn>=0.38.0",
+]
+
+[project.scripts]
+runa = "runa.cli.main:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "ruff>=0.16.4",
+    "pyright>=1.1.400",
+    "python-dotenv>=1.2.3",
+    "httpx>=0.28.0",
+    "runa[postgres,redis,ui]",
+    "mkdocs>=1.6.1",
+]
+
+[build-system]
+requires = ["uv_build >= 0.12.10, <0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "runa"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py314"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "B",
+    "SIM",
+    "UP",
+    "D",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "auto"
+
+[tool.pyright]
+include = [
+    "src",
+    "tests",
+    "examples",
+]
+reportIncompatibleMethodOverride = false

runa_ai-0.1.0/pyproject.toml.orig

@@ -0,0 +1,76 @@
+[project]
+name = "runa-ai"
+version = "0.1.0"
+authors = [
+    { name = "Brahim Benyous" },
+]
+description = "The application framework for agentic AI."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.14"
+dependencies = [
+    "anthropic>=0.75.0",
+    "graphviz>=0.21",
+    "httpx2>=2.12.0",
+    "mcp>=2.1.1",
+    "mkdocs-material>=9.7.7",
+    "pydantic>=2.9.0",
+    "pypdf>=6.0.0",
+    "sqlite-vec>=0.1.9",
+]
+
+[project.optional-dependencies]
+postgres = ["asyncpg>=0.30.0", "pgvector>=0.3.6"]
+redis = ["redis>=5.2.0"]
+ui = ["fastapi>=0.121.0", "uvicorn>=0.38.0"]
+
+[project.scripts]
+runa = "runa.cli.main:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "ruff>=0.16.4",
+    "pyright>=1.1.400",
+    "python-dotenv>=1.2.3",
+    "httpx>=0.28.0",
+    "runa[postgres,redis,ui]",
+    "mkdocs>=1.6.1",
+]
+
+[build-system]
+requires = ["uv_build >= 0.12.10, <0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "runa"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py314"
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "F",   # Pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "SIM", # flake8-simplify
+    "UP",  # pyupgrade
+    "D",   # docstring
+]
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "auto"
+
+[tool.pyright]
+include = ["src", "tests", "examples"]
+reportIncompatibleMethodOverride = false

runa_ai-0.1.0/src/runa/__init__.py

@@ -0,0 +1,79 @@
+"""Runa: an opinionated framework for agentic AI."""
+
+from runa.agent import Agent
+from runa.approval import approval
+from runa.cache import Cache, MemoryCache, SQLiteCache
+from runa.eval import (
+    DEFAULT_THRESHOLDS,
+    Case,
+    CaseReport,
+    Dataset,
+    EvaluationResult,
+    Report,
+    Status,
+)
+from runa.guardrail import guardrail
+from runa.knowledge import Knowledge, KnowledgeMatch
+from runa.lifecycle import AgentHooks, LoggingAgentHooks, LoggingRunHooks, RunHooks
+from runa.mcp import MCPServer, MCPServerStdio, MCPServerStreamableHttp
+from runa.memory import Memory, MemoryMatch
+from runa.result import RunResult, RunResultStreaming
+from runa.run import Run
+from runa.run_config import RunConfig
+from runa.run_state import Interruption, RunState
+from runa.runner import Runner
+from runa.session import SQLiteSession
+from runa.stream_events import (
+    AgentUpdatedStreamEvent,
+    RawResponsesStreamEvent,
+    RunItemStreamEvent,
+    StreamEvent,
+)
+from runa.tool import tool
+from runa.tracing import ConsoleExporter, Span, SQLiteExporter, Trace, TraceExporter, observe
+
+__all__ = [
+    "DEFAULT_THRESHOLDS",
+    "Agent",
+    "AgentHooks",
+    "AgentUpdatedStreamEvent",
+    "Cache",
+    "Case",
+    "CaseReport",
+    "ConsoleExporter",
+    "Dataset",
+    "EvaluationResult",
+    "Interruption",
+    "Knowledge",
+    "KnowledgeMatch",
+    "LoggingAgentHooks",
+    "LoggingRunHooks",
+    "MCPServer",
+    "MCPServerStdio",
+    "MCPServerStreamableHttp",
+    "Memory",
+    "MemoryCache",
+    "MemoryMatch",
+    "RawResponsesStreamEvent",
+    "Report",
+    "Run",
+    "RunConfig",
+    "RunHooks",
+    "RunItemStreamEvent",
+    "RunResult",
+    "RunResultStreaming",
+    "RunState",
+    "Runner",
+    "SQLiteCache",
+    "SQLiteExporter",
+    "SQLiteSession",
+    "Span",
+    "Status",
+    "StreamEvent",
+    "Trace",
+    "TraceExporter",
+    "approval",
+    "guardrail",
+    "observe",
+    "tool",
+]

runa_ai-0.1.0/src/runa/_graph.py

@@ -0,0 +1,63 @@
+"""_graph.py: `draw_graph`, a small DOT-graph generator behind `Agent.graph`.
+
+Not a port of `agents.extensions.visualization` -- just enough to show an agent's own tools and
+handoffs (recursively) as a Graphviz digraph, since that's all `Agent.graph` ever promised.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from graphviz import Digraph, Source
+
+
+def _agent_node_id(agent: Any) -> str:
+    return f"agent_{id(agent)}"
+
+
+def _add_agent(dot: Digraph, agent: Any, seen: set[int]) -> None:
+    if id(agent) in seen:
+        return
+    seen.add(id(agent))
+    node_id = _agent_node_id(agent)
+    dot.node(node_id, agent.name, shape="ellipse", style="filled", fillcolor="lightblue")
+
+    for tool in getattr(agent, "tools", []) or []:
+        tool_id = f"tool_{id(tool)}"
+        dot.node(
+            tool_id,
+            getattr(tool, "name", str(tool)),
+            shape="box",
+            style="filled",
+            fillcolor="lightyellow",
+        )
+        dot.edge(node_id, tool_id)
+
+    for server in getattr(agent, "mcp_servers", []) or []:
+        server_id = f"mcp_{id(server)}"
+        dot.node(
+            server_id,
+            getattr(server, "name", "mcp"),
+            shape="box",
+            style="filled,dashed",
+            fillcolor="lightgrey",
+        )
+        dot.edge(node_id, server_id)
+
+    for handoff in getattr(agent, "handoffs", []) or []:
+        target = getattr(handoff, "agent", handoff)
+        dot.edge(node_id, _agent_node_id(target), style="dashed")
+        _add_agent(dot, target, seen)
+
+
+def draw_graph(agent: Any) -> Source:
+    """Render `agent`, and its tools/handoffs/MCP servers (recursively), as a Graphviz `Source`."""
+    from graphviz import Digraph
+
+    dot = Digraph()
+    _add_agent(dot, agent, set())
+    return dot.unflatten(stagger=3)
+
+
+__all__ = ["draw_graph"]

runa_ai-0.1.0/src/runa/_models/__init__.py

@@ -0,0 +1,33 @@
+"""`runa._models`: Runa's own model provider — two backends, no `openai-agents`, no `openai` SDK.
+
+`ModelProvider.get_model` maps a model name's prefix to a backend. A name starting with `claude`
+goes through `AnthropicModel`, talking to Anthropic's own SDK directly — Anthropic's Messages API
+isn't chat-completions-shaped, so it's the one backend that needs real translation. Everything else
+(`gpt-*`, `gemini-*`, `llama-*`, `deepseek-*`, `qwen-*`, or an unrecognized/bare name) goes through
+`OpenAICompatibleModel`, which speaks the chat-completions wire format that OpenAI, Gemini, Llama,
+DeepSeek, and Qwen all share — over plain HTTP via `httpx2`, not the `openai` package.
+
+Conversation items are plain chat-completions-shaped message dicts everywhere in Runa (see
+`runa._types.TResponseInputItem`); `AnthropicModel` is the only place that ever converts away from
+that shape. Tools/handoffs are read structurally here (`.name`/`.description`/`.params_json_schema`
+for a tool, `.tool_name`/`.tool_description` for a handoff) rather than importing their concrete
+types, so this package has no dependency on `runa.tool`/`runa.handoff`.
+
+Split by concern: `interface` (the `Model` protocol, `StreamDelta`, shared wire-format helpers),
+`openai_chatcompletions` (the chat-completions backend), `anthropic` (the Claude backend), and
+`multi_provider` (`ModelProvider`, routing a model name to one of the two).
+"""
+
+from runa._models.anthropic import AnthropicModel
+from runa._models.anthropic import _anthropic_deltas as _anthropic_deltas
+from runa._models.anthropic import _check_plain_text_output as _check_plain_text_output
+from runa._models.anthropic import _to_anthropic_messages as _to_anthropic_messages
+from runa._models.anthropic import _to_anthropic_tool as _to_anthropic_tool
+from runa._models.anthropic import _to_anthropic_tool_choice as _to_anthropic_tool_choice
+from runa._models.anthropic import _to_chat_message as _to_chat_message
+from runa._models.anthropic import _to_usage as _to_usage
+from runa._models.interface import Model, StreamDelta
+from runa._models.multi_provider import ModelProvider
+from runa._models.openai_chatcompletions import OpenAICompatibleModel
+
+__all__ = ["AnthropicModel", "Model", "ModelProvider", "OpenAICompatibleModel", "StreamDelta"]