flowing-agent 0.1.0__tar.gz

flowing_agent-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: flowing-agent
+Version: 0.1.0
+Summary: A lightweight, extensible, descriptive agent runtime framework
+Author: Nyanifold
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Dist: aiohttp>=3.14.3
+Requires-Dist: croniter>=6.2.4
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: httpx2>=2.5.0
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: mcp>=2.0.0
+Requires-Dist: pydantic>=2.13.5
+Requires-Dist: ruamel-yaml>=0.19.1
+Requires-Python: >=3.13
+Project-URL: Repository, https://github.com/Nyanifold/flowing
+Project-URL: Documentation, https://flowing-agent.readthedocs.io/
+Project-URL: Issues, https://github.com/Nyanifold/flowing/issues
+Description-Content-Type: text/markdown
+
+# Flowing
+
+**English** | [中文](README.zh.md)
+
+Flowing is a lightweight, extensible, descriptive agent runtime framework for complex interactions (Python ≥ 3.13). In Flowing, an agent's entire definition — its role and prompt, the LLM it uses, its tools and subagents, composable extensions, and hook code — lives in a single `.fya` file. The framework opens its execution pipeline to extensions at key points, and its runtime can be embedded into any Python host application as an ordinary object. The core does only three things: message flow, error classification, and hook dispatch; policies such as retries, compaction, and approvals are mounted on demand as composables or plugins.
+
+## Who it's for
+
+- You want every layer of the framework to be readable, modifiable, and auditable, rather than a black box of policy configuration;
+- You need fine-grained control over conversation history — branching off from any message, rewriting or pruning the past, instead of append-only dialogue;
+- You need the same capability to present different model views on different agents, with an explicit safety boundary: being registered does not mean the model can see it.
+
+These needs don't point to any single application shape: in Flowing, orchestration logic is plain Python code, with sequencing, branching, and concurrency expressed by the language itself. As a foundational runtime framework, it can be used to build coding, education, e-commerce, or companion agents as well as multi-agent systems, and to run multi-agent interaction experiments.
+
+## Highlights
+
+- **Message-driven runtime model**: each agent instance owns a priority message queue and a persistent work loop; user input, model responses, tool results, external events, and subagent receipts are all represented as messages, each driving a turn. `query()` waits for the turn result, `message()` is fire-and-forget, `steer()` redirects an in-flight turn.
+- **A message-level tree for history**: conversation history is a forest of messages, not a linear list. `fork()` moves a cursor to open a parallel branch while old branches stay intact; history itself supports five surgical operations — insert, branch, remove, update, reparent — all persisted as usual.
+- **Three-layer capability description**: the executable object, the LLM-visible declaration, and the agent-level binding evolve independently — the same tool can appear under different names, descriptions, and parameter views on different agents. Built-in tools ship with the runtime, but they must be explicitly declared to become visible to the model.
+- **Declarative `.fya`**: an agent's description, model intent, capability bindings, system prompt, and hook code live in one self-contained file; the compiled output is fully equivalent to a hand-written `Agent` subclass.
+- **Instance-level hooks**: every instance has its own hook registry, with hook points spanning the lifecycle, turns, messages, model calls, tool execution, and subagents. A handler can rewrite data, asynchronously wait for external confirmation, or raise `Intercepted` to hard-block the operation — a natural foundation for human approval gates.
+- **Automatic persistence and crash recovery**: messages and state are persisted write-behind; after a crash, replay rebuilds the state. Unpaired tool calls are sealed during recovery, so the model always sees a complete, paired history.
+- **Zero-code tool access**: MCP servers (stdio / SSE / HTTP), shell command templates (arguments auto-escaped), and HTTP endpoints can all become tools from a single declaration file.
+- **Complete exposure options**: eight subcommands — REPL, one-shot CLI, plain HTTP API, a built-in web frontend, CI smoke tests, and more — run the same project unchanged in any form.
+
+## Installation
+
+```bash
+pip install flowing-agent
+```
+
+## Quick start
+
+Create a directory with five files.
+
+`root.fya`:
+
+```yaml
+description: Minimal Q&A assistant
+model_tag: default
+---
+$system_prompt:
+You are a concise assistant. Answer in at most three sentences.
+```
+
+`main.py`:
+
+```python
+from flowing import Runtime
+
+async def main() -> Runtime:
+    runtime = Runtime(persist_dir="@/.flowing")
+    runtime.set_model_tags("@/model-tags.yaml")
+    await runtime.mount("@/root.fya", agent_id="agent-main")
+    return runtime
+```
+
+Model access is split into three files, declaring the access identity, the model entries, and the tag mapping:
+
+```yaml
+# providers.yaml
+deepseek:
+  adapter: deepseek
+  base_url: https://api.deepseek.com
+  api_key: "{{env.DEEPSEEK_API_KEY}}"
+openrouter:
+  adapter: openrouter
+  base_url: https://openrouter.ai/api/v1
+  api_key: "{{env.OPENROUTER_API_KEY}}"
+```
+
+```yaml
+# models.yaml
+luna:
+  provider: openrouter
+  model: openai/gpt-6-luna
+  "reasoning.effort": high
+deepseek-flash:
+  provider: deepseek
+  model: deepseek-v4-flash
+```
+
+```yaml
+# model-tags.yaml
+tags:
+  default: luna
+```
+
+Run:
+
+```console
+$ export OPENROUTER_API_KEY='<your key>'
+$ flowing repl .
+(agent-main)>>> Introduce yourself in one sentence.
+I'm a concise assistant, keeping answers to three sentences or fewer.
+(agent-main)>>> /exit
+```
+
+The conversation doesn't vanish on exit: the messages it produced are persisted under `.flowing/` in the project directory. A fixed `agent_id` means that running `flowing repl .` again brings back the same agent with its full history — no recovery code required.
+
+## Going further
+
+- **Capability access**: declare built-in tools, MCP servers, or shell commands and HTTP endpoints as tools via `tools:`; implement custom logic with `ScriptTool`.
+- **Multi-agent**: declare subagent types under `subagents:` and the orchestrator routes work using the auto-generated catalog; you can also create subagents programmatically and run them in parallel.
+- **Intervention**: attach handlers at hook points — intercept a tool call pending approval, audit at turn completion, switch models and retry on provider errors. The built-in `use_retry` / `use_compact` are implemented in exactly this way and can serve as references.
+- **Embedding**: the host application holds the Runtime returned by `launch()`; input goes through `query` / `message` / `steer`, output through hook subscriptions (streaming output, completion notices, call interception).
+
+## Documentation
+
+- [Beginner tutorial](https://flowing-agent.readthedocs.io/en/beginner-tutorial/): for readers new to agent systems development;
+- [Detailed tutorial](https://flowing-agent.readthedocs.io/en/tutorial/): from quick start to core mechanics and operations;
+- [Concise reference](https://flowing-agent.readthedocs.io/en/flowing-ref/): the whole framework in four parts, for quick lookup;
+- [API reference](https://flowing-agent.readthedocs.io/en/api.html): the public API organized by module.
+
+## Project status
+
+Current version 0.1.0. The framework core is complete (700+ test cases passing) and the project is in the example-scenarios phase. Breaking changes are still possible during 0.x; every such release ships with a detailed changelog explaining how to migrate.
+
+This project was developed with heavy reliance on AI assistance, using models from different providers at different capability levels. Limited by the author's available time, not every line of code has been individually reviewed; if you find any divergence between the implementation and the documentation (docstrings, tutorials), an issue is greatly appreciated.
+
+## License
+
+[MIT](LICENSE) © 2026 Nyanifold
+
+---
+
+<p align="center">
+  <img src="assets/oh-wishes.svg" alt="Oh wishes... I beg you coalesce!">
+</p>

flowing_agent-0.1.0/README.md

@@ -0,0 +1,129 @@
+# Flowing
+
+**English** | [中文](README.zh.md)
+
+Flowing is a lightweight, extensible, descriptive agent runtime framework for complex interactions (Python ≥ 3.13). In Flowing, an agent's entire definition — its role and prompt, the LLM it uses, its tools and subagents, composable extensions, and hook code — lives in a single `.fya` file. The framework opens its execution pipeline to extensions at key points, and its runtime can be embedded into any Python host application as an ordinary object. The core does only three things: message flow, error classification, and hook dispatch; policies such as retries, compaction, and approvals are mounted on demand as composables or plugins.
+
+## Who it's for
+
+- You want every layer of the framework to be readable, modifiable, and auditable, rather than a black box of policy configuration;
+- You need fine-grained control over conversation history — branching off from any message, rewriting or pruning the past, instead of append-only dialogue;
+- You need the same capability to present different model views on different agents, with an explicit safety boundary: being registered does not mean the model can see it.
+
+These needs don't point to any single application shape: in Flowing, orchestration logic is plain Python code, with sequencing, branching, and concurrency expressed by the language itself. As a foundational runtime framework, it can be used to build coding, education, e-commerce, or companion agents as well as multi-agent systems, and to run multi-agent interaction experiments.
+
+## Highlights
+
+- **Message-driven runtime model**: each agent instance owns a priority message queue and a persistent work loop; user input, model responses, tool results, external events, and subagent receipts are all represented as messages, each driving a turn. `query()` waits for the turn result, `message()` is fire-and-forget, `steer()` redirects an in-flight turn.
+- **A message-level tree for history**: conversation history is a forest of messages, not a linear list. `fork()` moves a cursor to open a parallel branch while old branches stay intact; history itself supports five surgical operations — insert, branch, remove, update, reparent — all persisted as usual.
+- **Three-layer capability description**: the executable object, the LLM-visible declaration, and the agent-level binding evolve independently — the same tool can appear under different names, descriptions, and parameter views on different agents. Built-in tools ship with the runtime, but they must be explicitly declared to become visible to the model.
+- **Declarative `.fya`**: an agent's description, model intent, capability bindings, system prompt, and hook code live in one self-contained file; the compiled output is fully equivalent to a hand-written `Agent` subclass.
+- **Instance-level hooks**: every instance has its own hook registry, with hook points spanning the lifecycle, turns, messages, model calls, tool execution, and subagents. A handler can rewrite data, asynchronously wait for external confirmation, or raise `Intercepted` to hard-block the operation — a natural foundation for human approval gates.
+- **Automatic persistence and crash recovery**: messages and state are persisted write-behind; after a crash, replay rebuilds the state. Unpaired tool calls are sealed during recovery, so the model always sees a complete, paired history.
+- **Zero-code tool access**: MCP servers (stdio / SSE / HTTP), shell command templates (arguments auto-escaped), and HTTP endpoints can all become tools from a single declaration file.
+- **Complete exposure options**: eight subcommands — REPL, one-shot CLI, plain HTTP API, a built-in web frontend, CI smoke tests, and more — run the same project unchanged in any form.
+
+## Installation
+
+```bash
+pip install flowing-agent
+```
+
+## Quick start
+
+Create a directory with five files.
+
+`root.fya`:
+
+```yaml
+description: Minimal Q&A assistant
+model_tag: default
+---
+$system_prompt:
+You are a concise assistant. Answer in at most three sentences.
+```
+
+`main.py`:
+
+```python
+from flowing import Runtime
+
+async def main() -> Runtime:
+    runtime = Runtime(persist_dir="@/.flowing")
+    runtime.set_model_tags("@/model-tags.yaml")
+    await runtime.mount("@/root.fya", agent_id="agent-main")
+    return runtime
+```
+
+Model access is split into three files, declaring the access identity, the model entries, and the tag mapping:
+
+```yaml
+# providers.yaml
+deepseek:
+  adapter: deepseek
+  base_url: https://api.deepseek.com
+  api_key: "{{env.DEEPSEEK_API_KEY}}"
+openrouter:
+  adapter: openrouter
+  base_url: https://openrouter.ai/api/v1
+  api_key: "{{env.OPENROUTER_API_KEY}}"
+```
+
+```yaml
+# models.yaml
+luna:
+  provider: openrouter
+  model: openai/gpt-6-luna
+  "reasoning.effort": high
+deepseek-flash:
+  provider: deepseek
+  model: deepseek-v4-flash
+```
+
+```yaml
+# model-tags.yaml
+tags:
+  default: luna
+```
+
+Run:
+
+```console
+$ export OPENROUTER_API_KEY='<your key>'
+$ flowing repl .
+(agent-main)>>> Introduce yourself in one sentence.
+I'm a concise assistant, keeping answers to three sentences or fewer.
+(agent-main)>>> /exit
+```
+
+The conversation doesn't vanish on exit: the messages it produced are persisted under `.flowing/` in the project directory. A fixed `agent_id` means that running `flowing repl .` again brings back the same agent with its full history — no recovery code required.
+
+## Going further
+
+- **Capability access**: declare built-in tools, MCP servers, or shell commands and HTTP endpoints as tools via `tools:`; implement custom logic with `ScriptTool`.
+- **Multi-agent**: declare subagent types under `subagents:` and the orchestrator routes work using the auto-generated catalog; you can also create subagents programmatically and run them in parallel.
+- **Intervention**: attach handlers at hook points — intercept a tool call pending approval, audit at turn completion, switch models and retry on provider errors. The built-in `use_retry` / `use_compact` are implemented in exactly this way and can serve as references.
+- **Embedding**: the host application holds the Runtime returned by `launch()`; input goes through `query` / `message` / `steer`, output through hook subscriptions (streaming output, completion notices, call interception).
+
+## Documentation
+
+- [Beginner tutorial](https://flowing-agent.readthedocs.io/en/beginner-tutorial/): for readers new to agent systems development;
+- [Detailed tutorial](https://flowing-agent.readthedocs.io/en/tutorial/): from quick start to core mechanics and operations;
+- [Concise reference](https://flowing-agent.readthedocs.io/en/flowing-ref/): the whole framework in four parts, for quick lookup;
+- [API reference](https://flowing-agent.readthedocs.io/en/api.html): the public API organized by module.
+
+## Project status
+
+Current version 0.1.0. The framework core is complete (700+ test cases passing) and the project is in the example-scenarios phase. Breaking changes are still possible during 0.x; every such release ships with a detailed changelog explaining how to migrate.
+
+This project was developed with heavy reliance on AI assistance, using models from different providers at different capability levels. Limited by the author's available time, not every line of code has been individually reviewed; if you find any divergence between the implementation and the documentation (docstrings, tutorials), an issue is greatly appreciated.
+
+## License
+
+[MIT](LICENSE) © 2026 Nyanifold
+
+---
+
+<p align="center">
+  <img src="assets/oh-wishes.svg" alt="Oh wishes... I beg you coalesce!">
+</p>

flowing_agent-0.1.0/flowing/__init__.py

@@ -0,0 +1,188 @@
+"""``flowing`` —— 轻量式 Agent 框架：最终 API 规约（顶层导出）。
+
+.. rubric:: 功能介绍
+
+Flowing 的核心立场是“框架只提供机制，不提供策略”。包结构三层：
+
+- **框架核心**：``runtime`` / ``agent`` / ``agent_registry`` /
+  ``subagents`` / ``message`` / ``context`` /
+  ``parsable`` / ``params`` / ``tool``（子包）/ ``media`` / ``model`` /
+  ``hooks`` / ``lists`` / ``errors`` /
+  ``snapshot`` / ``providers`` / ``persistence`` / ``parser`` / ``paths`` /
+  ``provide`` / ``compiler`` —— 本模块顶层导出其中面向日常使用的符号。
+- **内置扩展**：``flowing.plugins``（``skills`` / ``comm`` / ``cron`` /
+  ``workflow`` / ``clipboard``）——随包发布、显式 ``runtime.install(...)`` 启用。
+- **应用层**：``flowing.composables``（以 ``use_xxx(agent, ...)`` 函数向
+  Agent 装配应用逻辑与策略）。
+
+运行模型锚点：消息级树（``Message.id`` + ``parent_id`` 链，
+``current_head_id`` 指向消息 id）；Turn 仅为逻辑执行阶段（执行期载体
+:class:`flowing.agent.TurnContext`，不落盘、不进树）；三层能力描述
+（可执行对象 / LLM 可见声明 / Agent 级绑定，推广到 Tool / 子 Agent /
+Skill）；provide-inject 沿 ``_parent_id`` 链上溯；实例级钩子系统。
+
+.. rubric:: 设计动机
+
+顶层导出收敛到“写一个 Agent 项目一定会 import”的最小集合；其余符号
+（异常明细、快照视图、内部容器）经子模块显式导入，保持顶层命名空间
+可读、可记忆。
+
+.. rubric:: 使用示例
+
+.. code-block:: python
+
+    # @/main.py —— 子项目入口约定
+    import flowing
+    from flowing import Runtime, on
+
+    async def main(**kwargs) -> Runtime:
+        runtime = flowing.Runtime()      # @ 由 launch 上下文自动绑定
+        runtime.install(...)              # 阶段一：安装扩展
+        await runtime.mount("@/root.fya") # 创建根 Agent
+        return runtime
+
+.. code-block:: bash
+
+    flowing run <path>   # launch(path) → await runtime → SIGINT → shutdown
+
+.. rubric:: 行为规约
+
+- ``flowing.launch(path, **kwargs)`` 是 Runtime 的**唯一创建入口**；
+  绕过它直接 ``Runtime()`` 因无 ``@`` 上下文抛 ``RuntimeError``。
+- 本模块只做 re-export，不定义任何新符号；各符号的完整契约见所属
+  子模块的规约。
+- 稳定性：本模块导出的全部符号属跨版本稳定契约；``_`` 前缀符号与
+  ``flowing.interfaces.cli`` / ``flowing.interfaces.web`` 的细节不属稳定边界。
+"""
+
+from flowing.agent import (
+    Agent,
+    CancelContext,
+    Execution,
+    FieldUpdate,
+    ProviderErrorContext,
+    TurnContext,
+    TurnResult,
+)
+from flowing.agent_registry import AgentRegistry
+from flowing.context import Context, PromptBlock, PromptBlockList, PromptSegment
+from flowing.errors import FlowingError, Intercepted
+from flowing.hooks import HookRegistry, on
+from flowing.lists import ManagedList
+from flowing.message import (
+    ContentBlock,
+    FileBlock,
+    ImageBlock,
+    MediaBlock,
+    Message,
+    MessageChain,
+    MessageKind,
+    MessagePriority,
+    MessageQueue,
+    StructBlock,
+    TextBlock,
+    ThinkingBlock,
+    ToolCallBlock,
+)
+from flowing.model import (
+    ModelConfig,
+)
+from flowing.params import ConfigKey, InjectionKey
+from flowing.parsable import PENDING, Parsable
+from flowing.plugins import Plugin
+from flowing.provide import ProvideNode
+from flowing.providers import (
+    Provider,
+    ProviderConfig,
+    ProviderDelta,
+    ProviderResponse,
+    Usage,
+)
+from flowing.builtins import FinishTool, SubagentInvokeTool
+from flowing.runtime import Runtime, launch, resolve
+from flowing.subagents import SubagentEntry, SubagentInvocation, SubagentResult
+from flowing.tool import (
+    Audio,
+    File,
+    Image,
+    ScriptTool,
+    Tool,
+    ToolCall,
+    ToolDefinition,
+    ToolEntry,
+    ToolRegistry,
+    ToolResult,
+    Video,
+    flowing_tool,
+    normalize_output,
+    output_to_blocks,
+    register_media_converter,
+)
+
+__all__ = [
+    "Agent",
+    "AgentRegistry",
+    "Audio",
+    "CancelContext",
+    "ConfigKey",
+    "ContentBlock",
+    "Context",
+    "Execution",
+    "FieldUpdate",
+    "File",
+    "FileBlock",
+    "FinishTool",
+    "FlowingError",
+    "ScriptTool",
+    "HookRegistry",
+    "Image",
+    "ImageBlock",
+    "InjectionKey",
+    "Intercepted",
+    "ManagedList",
+    "MediaBlock",
+    "Message",
+    "MessageChain",
+    "MessageKind",
+    "MessagePriority",
+    "MessageQueue",
+    "ModelConfig",
+    "PENDING",
+    "Parsable",
+    "Plugin",
+    "PromptBlock",
+    "PromptBlockList",
+    "PromptSegment",
+    "ProvideNode",
+    "Provider",
+    "ProviderConfig",
+    "ProviderDelta",
+    "ProviderResponse",
+    "ProviderErrorContext",
+    "Runtime",
+    "StructBlock",
+    "SubagentEntry",
+    "SubagentInvocation",
+    "SubagentInvokeTool",
+    "SubagentResult",
+    "TextBlock",
+    "ThinkingBlock",
+    "Tool",
+    "ToolCall",
+    "ToolCallBlock",
+    "ToolDefinition",
+    "ToolEntry",
+    "ToolRegistry",
+    "ToolResult",
+    "TurnContext",
+    "TurnResult",
+    "Usage",
+    "Video",
+    "flowing_tool",
+    "launch",
+    "normalize_output",
+    "on",
+    "output_to_blocks",
+    "register_media_converter",
+    "resolve",
+]

flowing_agent-0.1.0/flowing/_unstable/__init__.py

@@ -0,0 +1,30 @@
+"""``flowing._unstable`` —— 实验性命名空间：可导入，但不冻结。
+
+.. rubric:: 功能介绍
+
+本包收容“功能已确定、策略 / 接口形态未确定”的自用设施。与
+:mod:`flowing.plugins` 的区别在稳定性承诺：
+
+- ``flowing.plugins.*``：内置扩展，契约随框架版本冻结（签名、语义、
+  持久化格式按正常版本纪律演进）。
+- ``flowing._unstable.*``：允许在任何版本中改签名、改名、改语义、
+  整体删除或迁出，不视为 breaking change，不发迁移通告。下划线
+  前缀同时挡住自动导入与“稳定 API”的心理预期。
+
+.. rubric:: 毕业规则
+
+某设施的策略确定后，整体迁往正式包（如 ``flowing.plugins``）并在本
+包留一个 re-export 过渡（仅当下一个 minor 版本）；迁入正式包后按
+正常稳定性纪律管理。
+
+.. rubric:: 使用约定
+
+- 仅自用 / 内部 debug 场景；下游发布物（插件、workflow、技能包）
+  禁止依赖本包。
+- 本包模块的持久化产物（如日志文件）不构成恢复依赖——框架任何恢复
+  路径不得读取 ``_unstable`` 设施写出的文件。
+
+当前内容：:mod:`flowing._unstable.logging` （钩子链路日志插件）。
+"""
+
+__all__: list[str]