picoflow 0.1.1__tar.gz

picoflow-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the-picoflow
+
+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.

picoflow-0.1.1/PKG-INFO

@@ -0,0 +1,240 @@
+Metadata-Version: 2.1
+Name: picoflow
+Version: 0.1.1
+Summary: Simple, flexible AI agent framework with a small DSL and explicit state
+Author: PicoFlow Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/the-picoflow/picoflow
+Project-URL: Repository, https://github.com/the-picoflow/picoflow
+Project-URL: Issues, https://github.com/the-picoflow/picoflow/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+<p align="center">
+  <img src="picoflow/assets/picoflow_logo.png" width="280">
+</p>
+
+# PicoFlow — Simple, Flexible AI Agent Framework
+
+**Build agents with explicit steps and a small DSL.  
+LLMs, tools, loops, and branches compose naturally.**
+
+---
+
+## A Minimal PicoFlow Application
+
+```python
+from picoflow import flow, llm, create_agent
+
+LLM_URL = "llm+openai://api.openai.com/v1/chat/completions?model=gpt-4.1-mini&api_key_env=OPENAI_API_KEY"
+
+@flow
+async def mem(ctx):
+    return ctx.add_memory("user", ctx.input)
+
+agent = create_agent(
+    mem >> llm("Answer in one sentence: {input}", llm_adapter=LLM_URL)
+)
+
+print(agent.get_output("What is PicoFlow?", trace=True))
+```
+
+```bash
+export OPENAI_API_KEY=sk-...
+python minimal.py
+```
+
+---
+
+## Core Ideas
+
+- **Flow = step**  
+  A flow is just a Python function that takes and returns `State`.
+
+- **DSL = pipeline**  
+  Use `>>` to compose steps into readable execution graphs.
+
+- **Agent = runner**  
+  `create_agent(flow)` gives you `run / arun / get_output`.
+
+- **State = context (Ctx)**  
+  `Ctx` is an alias of `State`. It is immutable and explicit.
+
+---
+
+## Quick Start (Step by Step)
+
+### 1. Define Steps with `@flow`
+
+```python
+from picoflow import flow, Ctx
+
+@flow
+async def normalize(ctx: Ctx) -> Ctx:
+    return ctx.update(input=ctx.input.strip().lower())
+```
+
+---
+
+### 2. Call LLM as a Step
+
+```python
+from picoflow import llm
+
+ask = llm("Answer briefly: {input}")
+```
+
+---
+
+### 3. Compose with DSL
+
+```python
+pipeline = normalize >> ask
+```
+
+---
+
+### 4. Run with Agent
+
+```python
+from picoflow import create_agent
+
+agent = create_agent(pipeline)
+
+state = await agent.arun("Hello WORLD")
+print(state.output)
+```
+
+---
+
+## DSL in One Minute
+
+### Sequential
+
+```python
+flow = a >> b >> c
+```
+
+### Loop
+
+```python
+flow = step.repeat()
+```
+
+or:
+
+```python
+flow = repeat(step, until=lambda s: s.done)
+```
+
+### Parallel + Merge
+
+```python
+flow = fork(a, b) >> merge()
+```
+
+Custom merge:
+
+```python
+flow = fork(a, b) >> merge(
+    mode=MergeType.CUSTOM,
+    reducer=lambda branches, main: branches[0]
+)
+```
+
+---
+
+## LLM URL
+
+```python
+from picoflow.adapters.registry import from_url
+
+adapter = from_url(
+    "llm+openai://api.openai.com/v1/chat/completions"
+    "?model=gpt-4.1-mini&api_key_env=OPENAI_API_KEY"
+)
+```
+
+Then:
+
+```python
+flow = llm("Explain: {input}", llm_adapter=adapter)
+```
+
+### Custom Adapters
+
+```python
+class MyAdapter(LLMAdapter):
+    def __call__(self, prompt: str, stream: bool):
+        ...
+```
+
+```python
+from picoflow.adapters.registry import register
+
+register("myllm", lambda url: MyAdapter(...))
+```
+
+Use:
+
+```
+llm+myllm://host/model?param=value
+```
+
+---
+
+## Runtime Options
+
+### Tracing
+
+```python
+await agent.arun("hi", trace=True)
+```
+
+### Timeout
+
+```python
+await agent.arun("hi", timeout=10)
+```
+
+### Streaming
+
+```python
+async def on_chunk(text: str):
+    print(text, end="", flush=True)
+
+await agent.arun("stream me", stream_callback=on_chunk)
+```
+
+---
+
+## Tools
+
+```python
+from picoflow import tool
+
+flow = tool("search", lambda q: {"result": "..."} )
+```
+
+Results:
+
+```python
+state.tools["search"]
+```
+
+---
+
+## License
+
+MIT

picoflow-0.1.1/README.md

@@ -0,0 +1,217 @@
+<p align="center">
+  <img src="picoflow/assets/picoflow_logo.png" width="280">
+</p>
+
+# PicoFlow — Simple, Flexible AI Agent Framework
+
+**Build agents with explicit steps and a small DSL.  
+LLMs, tools, loops, and branches compose naturally.**
+
+---
+
+## A Minimal PicoFlow Application
+
+```python
+from picoflow import flow, llm, create_agent
+
+LLM_URL = "llm+openai://api.openai.com/v1/chat/completions?model=gpt-4.1-mini&api_key_env=OPENAI_API_KEY"
+
+@flow
+async def mem(ctx):
+    return ctx.add_memory("user", ctx.input)
+
+agent = create_agent(
+    mem >> llm("Answer in one sentence: {input}", llm_adapter=LLM_URL)
+)
+
+print(agent.get_output("What is PicoFlow?", trace=True))
+```
+
+```bash
+export OPENAI_API_KEY=sk-...
+python minimal.py
+```
+
+---
+
+## Core Ideas
+
+- **Flow = step**  
+  A flow is just a Python function that takes and returns `State`.
+
+- **DSL = pipeline**  
+  Use `>>` to compose steps into readable execution graphs.
+
+- **Agent = runner**  
+  `create_agent(flow)` gives you `run / arun / get_output`.
+
+- **State = context (Ctx)**  
+  `Ctx` is an alias of `State`. It is immutable and explicit.
+
+---
+
+## Quick Start (Step by Step)
+
+### 1. Define Steps with `@flow`
+
+```python
+from picoflow import flow, Ctx
+
+@flow
+async def normalize(ctx: Ctx) -> Ctx:
+    return ctx.update(input=ctx.input.strip().lower())
+```
+
+---
+
+### 2. Call LLM as a Step
+
+```python
+from picoflow import llm
+
+ask = llm("Answer briefly: {input}")
+```
+
+---
+
+### 3. Compose with DSL
+
+```python
+pipeline = normalize >> ask
+```
+
+---
+
+### 4. Run with Agent
+
+```python
+from picoflow import create_agent
+
+agent = create_agent(pipeline)
+
+state = await agent.arun("Hello WORLD")
+print(state.output)
+```
+
+---
+
+## DSL in One Minute
+
+### Sequential
+
+```python
+flow = a >> b >> c
+```
+
+### Loop
+
+```python
+flow = step.repeat()
+```
+
+or:
+
+```python
+flow = repeat(step, until=lambda s: s.done)
+```
+
+### Parallel + Merge
+
+```python
+flow = fork(a, b) >> merge()
+```
+
+Custom merge:
+
+```python
+flow = fork(a, b) >> merge(
+    mode=MergeType.CUSTOM,
+    reducer=lambda branches, main: branches[0]
+)
+```
+
+---
+
+## LLM URL
+
+```python
+from picoflow.adapters.registry import from_url
+
+adapter = from_url(
+    "llm+openai://api.openai.com/v1/chat/completions"
+    "?model=gpt-4.1-mini&api_key_env=OPENAI_API_KEY"
+)
+```
+
+Then:
+
+```python
+flow = llm("Explain: {input}", llm_adapter=adapter)
+```
+
+### Custom Adapters
+
+```python
+class MyAdapter(LLMAdapter):
+    def __call__(self, prompt: str, stream: bool):
+        ...
+```
+
+```python
+from picoflow.adapters.registry import register
+
+register("myllm", lambda url: MyAdapter(...))
+```
+
+Use:
+
+```
+llm+myllm://host/model?param=value
+```
+
+---
+
+## Runtime Options
+
+### Tracing
+
+```python
+await agent.arun("hi", trace=True)
+```
+
+### Timeout
+
+```python
+await agent.arun("hi", timeout=10)
+```
+
+### Streaming
+
+```python
+async def on_chunk(text: str):
+    print(text, end="", flush=True)
+
+await agent.arun("stream me", stream_callback=on_chunk)
+```
+
+---
+
+## Tools
+
+```python
+from picoflow import tool
+
+flow = tool("search", lambda q: {"result": "..."} )
+```
+
+Results:
+
+```python
+state.tools["search"]
+```
+
+---
+
+## License
+
+MIT

picoflow-0.1.1/picoflow/__init__.py

@@ -0,0 +1,3 @@
+from .core import *
+
+__version__ = "0.1.1"

picoflow-0.1.1/picoflow/adapters/__init__.py

@@ -0,0 +1,5 @@
+from .registry import from_url, register_llm_provider
+
+from . import openai_compat, ollama
+
+__all__ = ["from_url", "register_llm_provider"]

picoflow-0.1.1/picoflow/adapters/_http.py

@@ -0,0 +1,46 @@
+# adapters/_http.py
+import json
+import urllib.error
+import asyncio
+from typing import Callable, TypeVar
+
+T = TypeVar("T")
+
+
+async def run_blocking(fn: Callable[[], T]) -> T:
+    loop = asyncio.get_running_loop()
+    return await loop.run_in_executor(None, fn)
+
+
+def raise_http_error(e: urllib.error.HTTPError, *, provider: str, hint: str = "") -> None:
+    body = None
+    try:
+        raw = e.read().decode("utf-8", errors="ignore")
+        if raw:
+            try:
+                obj = json.loads(raw)
+                # OpenAI-style: {"error": {"message": "..."}}
+                if isinstance(obj, dict):
+                    if "error" in obj and isinstance(obj["error"], dict):
+                        body = obj["error"].get("message")
+                    else:
+                        body = raw
+            except Exception:
+                body = raw
+    except Exception:
+        pass
+
+    msg = f"[{provider}] HTTP {e.code} {e.reason}"
+    if body:
+        msg += f": {body}"
+    if hint:
+        msg += f"\nHint: {hint}"
+
+    raise RuntimeError(msg) from None
+
+
+def raise_url_error(e: urllib.error.URLError, *, provider: str, hint: str = "") -> None:
+    msg = f"[{provider}] Network error: {e.reason}"
+    if hint:
+        msg += f"\nHint: {hint}"
+    raise RuntimeError(msg) from None