graphrefly 0.1.0__py3-none-any.whl

graphrefly/py.typed

@@ -0,0 +1 @@
+

graphrefly-0.1.0.dist-info/METADATA

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: graphrefly
+Version: 0.1.0
+Summary: Reactive graph protocol for human + LLM co-operation. Composable nodes, glitch-free diamond resolution, two-phase push, durable streaming. Zero dependencies.
+Project-URL: Homepage, https://py.graphrefly.dev
+Project-URL: Repository, https://github.com/graphrefly/graphrefly-py
+Project-URL: Documentation, https://py.graphrefly.dev
+Author: David Chen
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,asyncio,callbag,diamond-resolution,durable-workflow,graph,llm,observable,orchestration,reactive,reactive-programming,signals,state-management,streaming,zero-dependency
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# GraphReFly
+
+**Reactive graph protocol for human + LLM co-operation.**
+
+One primitive. Zero dependencies. Composable nodes with glitch-free diamond resolution, two-phase push propagation, durable streaming, and async runners for asyncio and trio.
+
+[![PyPI](https://img.shields.io/pypi/v/graphrefly-py?color=blue)](https://pypi.org/project/graphrefly-py/)
+[![license](https://img.shields.io/github/license/graphrefly/graphrefly-py)](./LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/graphrefly-py)](https://pypi.org/project/graphrefly-py/)
+
+[Docs](https://py.graphrefly.dev) | [Spec](https://py.graphrefly.dev/spec/) | [TypeScript](https://graphrefly.dev) | [API Reference](https://py.graphrefly.dev/api/)
+
+---
+
+## Quick start
+
+```bash
+pip install graphrefly-py
+```
+
+```python
+from graphrefly import state, derived, effect
+
+count = state(0)
+doubled = derived([count], lambda deps, _: deps[0] * 2)
+
+effect([doubled], lambda deps, _: print("doubled:", deps[0]))
+# → doubled: 0
+
+count.push(3)
+# → doubled: 6
+```
+
+## Why GraphReFly?
+
+Most state libraries solve **one** problem well. GraphReFly solves the space between them:
+
+|  | Redux / Zustand | RxPY | Pydantic AI | TC39 Signals | **GraphReFly** |
+|--|-----------------|------|-------------|-------------|---------------|
+| Simple store API | yes | no | no | yes | **yes** |
+| Streaming operators | no | yes | no | no | **yes** |
+| Diamond resolution | no | n/a | n/a | partial | **glitch-free** |
+| Graph introspection | no | no | no | no | **describe / observe / diagram** |
+| Durable checkpoints | no | no | no | no | **file / SQLite / IndexedDB** |
+| LLM orchestration | no | no | partial | no | **agent_loop / chat_stream / tool_registry** |
+| Async runners | n/a | asyncio | asyncio | n/a | **asyncio / trio** |
+| Dependencies | varies | 0 | many | n/a | **0** |
+
+## One primitive
+
+Everything is a `node`. Sugar constructors give you the right shape:
+
+```python
+from graphrefly import state, derived, producer, effect
+from graphrefly.core.messages import DATA
+
+# Writable state
+name = state("world")
+
+# Computed (re-runs when deps change)
+greeting = derived([name], lambda deps, _: f"Hello, {deps[0]}!")
+
+# Push source (timers, events, async streams)
+clock = producer(lambda emit, _: emit([(DATA, time.time())]))
+
+# Side effect
+effect([greeting], lambda deps, _: print(deps[0]))
+```
+
+## Streaming & operators
+
+70+ operators — transform, combine, buffer, window, rate-limit, retry, circuit-break:
+
+```python
+from graphrefly.extra.tier1 import map_op, filter_op, scan
+from graphrefly.extra.tier2 import switch_map, debounce_time
+from graphrefly.extra.resilience import retry
+from graphrefly import pipe
+
+search = pipe(
+    user_input,
+    debounce_time(0.3),
+    switch_map(lambda q: from_promise(fetch(f"/api?q={q}"))),
+    retry(strategy="exponential", max_attempts=3),
+)
+```
+
+## Graph container
+
+Register nodes in a `Graph` for introspection, snapshot, and persistence:
+
+```python
+from graphrefly import Graph, state, derived
+
+g = Graph("pricing")
+price = g.register("price", state(100))
+tax   = g.register("tax", derived([price], lambda d, _: d[0] * 0.1))
+total = g.register("total", derived([price, tax], lambda d, _: d[0] + d[1]))
+
+g.describe()   # → full graph topology as dict
+g.diagram()    # → Mermaid diagram string
+g.observe(lambda e: print(e))  # → live change stream
+```
+
+## AI & orchestration
+
+First-class patterns for LLM streaming, agent loops, and human-in-the-loop workflows:
+
+```python
+from graphrefly.patterns.ai import chat_stream, agent_loop, tool_registry
+from graphrefly.patterns.memory import collection, decay
+
+# Streaming chat with tool use
+chat = chat_stream("assistant", model="claude-sonnet-4-20250514",
+                   tools=tool_registry("tools", search=search_fn))
+
+# Full agent loop: observe → think → act → memory
+agent = agent_loop("researcher", llm=chat,
+                   memory=agent_memory(decay="openviking"))
+```
+
+## Async runners
+
+Native asyncio and trio support for async sources and long-running graphs:
+
+```python
+from graphrefly.compat.asyncio_runner import AsyncioRunner
+from graphrefly.extra.sources import from_async_iter
+
+# Wrap an async generator as a reactive node
+async def sse_events():
+    async for event in httpx_client.stream("GET", "/events"):
+        yield event.data
+
+events = from_async_iter(sse_events())
+
+# Run the graph in an asyncio event loop
+runner = AsyncioRunner(graph)
+await runner.run()
+```
+
+## FastAPI integration
+
+Drop-in integration for reactive backends:
+
+```python
+from graphrefly.integrations.fastapi import GraphReflyRouter
+
+router = GraphReflyRouter(graph)
+app.include_router(router, prefix="/graph")
+# GET /graph/describe  → graph topology
+# GET /graph/snapshot  → current state
+# WS  /graph/observe   → live change stream
+```
+
+## Resilience & checkpoints
+
+Built-in retry, circuit breakers, rate limiters, and persistent checkpoints:
+
+```python
+from graphrefly.extra.resilience import retry, circuit_breaker, rate_limiter
+from graphrefly.extra.checkpoint import FileCheckpointAdapter, save_graph_checkpoint
+
+# Retry with exponential backoff
+resilient = pipe(source, retry(strategy="exponential"))
+
+# Circuit breaker
+breaker = circuit_breaker(threshold=5, reset_timeout=30.0)
+
+# Checkpoint to file system
+adapter = FileCheckpointAdapter("./checkpoints")
+save_graph_checkpoint(graph, adapter)
+```
+
+## Project layout
+
+| Path | Contents |
+|------|----------|
+| `src/graphrefly/core/` | Message protocol, `node` primitive, batch, sugar constructors |
+| `src/graphrefly/extra/` | Operators, sources, data structures, resilience, checkpoints |
+| `src/graphrefly/graph/` | `Graph` container, describe/observe, snapshot, persistence |
+| `src/graphrefly/patterns/` | Orchestration, messaging, memory, AI, CQRS, reactive layout |
+| `src/graphrefly/compat/` | Async runners (asyncio, trio) |
+| `src/graphrefly/integrations/` | Framework integrations (FastAPI) |
+| `docs/` | Roadmap, guidance, benchmarks |
+| `website/` | Astro + Starlight docs site ([py.graphrefly.dev](https://py.graphrefly.dev)) |
+
+## Scripts
+
+```bash
+uv run pytest              # run tests
+uv run ruff check .        # lint
+uv run mypy src/           # type check
+uv run pytest --benchmark  # benchmarks
+```
+
+## Requirements
+
+Python 3.12 or later. Zero runtime dependencies.
+
+## Acknowledgments
+
+GraphReFly builds on ideas from many projects and papers:
+
+**Protocol & predecessor:**
+- **[Callbag](https://github.com/callbag/callbag)** (Andre Staltz) — the original reactive protocol spec. GraphReFly's message-based node communication descends from callbag's function-calling-function model.
+- **[callbag-recharge](https://github.com/Callbag-Recharge/callbag-recharge)** & **[callbag-recharge-py](https://github.com/Callbag-Recharge/callbag-recharge-py)** — GraphReFly's direct predecessors. The Python port (6 primitives, 18 operators, 100+ tests) established cross-language parity patterns carried forward.
+
+**Reactive design patterns:**
+- **[SolidJS](https://github.com/solidjs/solid)** — two-phase execution (DIRTY propagation + value flow), automatic caching, and effect batching. Closest philosophical neighbor.
+- **[Preact Signals](https://github.com/preactjs/signals)** — fine-grained reactivity and cached-flag optimization patterns that informed RESOLVED signal design.
+- **[TC39 Signals Proposal](https://github.com/tc39/proposal-signals)** — the `.get()/.set()` contract and the push toward language-level reactivity.
+- **[RxJS](https://github.com/ReactiveX/rxjs)** / **[RxPY](https://github.com/ReactiveX/RxPY)** — operator naming conventions and the DevTools observability philosophy that inspired the Inspector pattern.
+
+**AI & memory:**
+- **[OpenViking](https://github.com/volcengine/openviking)** (Volcengine) — the memory decay formula (`sigmoid(log1p(count)) * exp_decay(age, 7d)`) and L0/L1/L2 progressive loading strategy used in `agent_memory()`.
+- **[FadeMem](https://arxiv.org/abs/2501.09399)** (Wei et al., ICASSP 2026) — biologically-inspired dual-layer memory with adaptive exponential decay.
+- **[MAGMA](https://arxiv.org/abs/2501.13920)** (Jiang et al., 2026) — four-parallel-graph model (semantic/temporal/causal/entity) that informed `knowledge_graph()` design.
+- **[Letta/MemGPT](https://github.com/letta-ai/letta)**, **[Mem0](https://github.com/mem0ai/mem0)**, **[Zep/Graphiti](https://github.com/getzep/graphiti)**, **[Cognee](https://github.com/topoteretes/cognee)** — production memory architectures surveyed during `agent_memory()` design.
+
+**Layout & other:**
+- **[Pretext](https://github.com/chenglou/pretext)** (Cheng Lou) — inspired the reactive layout engine's DOM-free text measurement pipeline.
+- **[CASL](https://github.com/stalniy/casl)** — declarative `allow()`/`deny()` policy builder DX that inspired `policy()`.
+- **[Nanostores](https://github.com/nanostores/nanostores)** — tiny framework-agnostic API with `.get()/.set()/.subscribe()` mapping that validated the store ergonomics.
+
+## License
+
+[MIT](./LICENSE)

graphrefly-0.1.0.dist-info/RECORD

@@ -0,0 +1,47 @@
+graphrefly/__init__.py,sha256=wXd13rcP39eu4yrqZ4ycCWDyzmiLtXUpMQgdwPzvluU,3040
+graphrefly/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+graphrefly/compat/__init__.py,sha256=HWfCAXg5kKuo7s8qy6r-nSElyWQnQ24MDpI8YmTgZ2g,496
+graphrefly/compat/async_utils.py,sha256=1pCwdJwU4AJwiMScrgNNM3VEuEiBvEKOWyKHPJQJo9s,7501
+graphrefly/compat/asyncio_runner.py,sha256=fDFh1ej6n4ziaRbzjQrU__DsG8x2zOFxc46cDAUg74c,2460
+graphrefly/compat/trio_runner.py,sha256=Z8RT-JzMedzJuGgurzb1PSitpuOPP2UeBmfWmoSUGJA,2079
+graphrefly/core/__init__.py,sha256=UdX9w8bVZf07sIxPGByN20lf6FHtbYHf0buQqk2gTWU,2820
+graphrefly/core/clock.py,sha256=AxtKX8yj5a5NG-JoUo5jrXemWuOAckjQ2HlbkiqzhGA,611
+graphrefly/core/dynamic_node.py,sha256=zHUezZv2WwKrnXTdnifYzqREd_jx0gkvvEiPtX7lmP0,25589
+graphrefly/core/guard.py,sha256=snNOkmf2fDvOorjMWYuEYKEWrVSgLzgMNqnuTKJ_Dds,8879
+graphrefly/core/meta.py,sha256=3IqCx6zZ6d2aYkaUeY8POvh8o6btXFDhZP43N9v_1vY,4970
+graphrefly/core/node.py,sha256=XN9wtRkJOdzzfKHErRhFyI_GDccBTuTkqtuxDd43sbU,33436
+graphrefly/core/protocol.py,sha256=DNNeiGXW3DcOz1k8T030ZjYrK1R67OAMMNFG8_rk6yM,16121
+graphrefly/core/runner.py,sha256=R-1jpJ9wsVbCGfQd6oNgzBpF_HatT1pAtlmdTbxMcBg,3281
+graphrefly/core/subgraph_locks.py,sha256=xa4563Pd_67gd0AVdRbsMlVAJXNq_9tMGqwicQTC2A8,10348
+graphrefly/core/sugar.py,sha256=9FW9BWrose6CHP-mfEd10z6EacJQpNNYMVCoFu5Yx5k,4276
+graphrefly/core/versioning.py,sha256=mHBDN6PUoRj_IkpAWW1tIdmeTo9bdP33u1Ak4GzmLNw,6177
+graphrefly/extra/__init__.py,sha256=vjuK5HXg5sDzAs4woV9IAfliT0H4cR45iVGlY-QG6As,5714
+graphrefly/extra/adapters.py,sha256=J1ItOwl92Cw7XGWpfpjKbXc1Tqga8BXdBiIGHstlAnQ,71844
+graphrefly/extra/backoff.py,sha256=oNPrspj1lsKAd7X_nvlPL1hm35EewcLQgImHkdw-UBY,8682
+graphrefly/extra/backpressure.py,sha256=BuwC05lxgdD5AXTN3Btk8PbpCUp70va05B8PM2GvKeo,3614
+graphrefly/extra/checkpoint.py,sha256=2REZmSS4u5lwsS-8WW6T26WjpWsokJQWxOw87oWYfSg,10213
+graphrefly/extra/composite.py,sha256=75ExK2tBkHIIVjD7EwzTZKnhqvXQQr0TYguWVXOpsGw,9894
+graphrefly/extra/cron.py,sha256=tvFSz6l_H2JED5YeRmn1Fdo_jtY9eDJInCfOfAVci_I,4341
+graphrefly/extra/data_structures.py,sha256=YIxYKbcNa3w-wbmgBdZQmSlVK1mCUaTZvFqsueDBWPs,22759
+graphrefly/extra/resilience.py,sha256=n4pzyC89qrZ8MwOZl8lhQdIsIN4w9rljCo-TfRtykEA,24283
+graphrefly/extra/sources.py,sha256=KswMDju2gp8mt3tfob3OgGnrMgy3S7b9ewdjcXJ7aHM,23194
+graphrefly/extra/tier1.py,sha256=vIF1w0iqEJTCuwkbaDpwt18NXHzX8wpCrIHuPFlQhQ0,32452
+graphrefly/extra/tier2.py,sha256=8_pwI5r_0vfQZWHiQd-JdFB-8NOXloVRqOsYrkzbrbA,58319
+graphrefly/graph/__init__.py,sha256=q7KGCueLgmc8fc--yHuBbOcmcE8J621We-EwPhziB5Y,624
+graphrefly/graph/graph.py,sha256=J1eBNeXLErljPNQCVw5_0v1rTHTC0xUWuh2lUQ8rzkg,85114
+graphrefly/integrations/__init__.py,sha256=TQIsQDM4E8lUR52P-qQx6XTC6Rbtl_hhsSdFGAD0rhc,61
+graphrefly/integrations/fastapi.py,sha256=1TCH0k2Wi7OuZaNoY1LggU7p0KGCl0GYAK3DjfZXh4U,25795
+graphrefly/patterns/__init__.py,sha256=Lyxovgdt9OCtqde7D1hw2YMzCWH1z1CfKXFCmffT_e0,226
+graphrefly/patterns/ai.py,sha256=z6ko-vvZTmajxu--3VorlI_qPckrhfpSCWR9m4AqC54,73538
+graphrefly/patterns/cqrs.py,sha256=2doCBqwe78qV7epP9uTtpgblWawuuBsjqKYcvwpZzt8,17716
+graphrefly/patterns/memory.py,sha256=NlSjp1Lu7UdLeVW59R0EdIEAJAZqWjmVp30q49ZqaW8,20422
+graphrefly/patterns/messaging.py,sha256=ejGgcrM8DW0e1FphVHNOhD6Nnsn0LpA3yHIzNtImFGQ,17891
+graphrefly/patterns/orchestration.py,sha256=Zs60tzL5yCHT--kSAj_tNCcbaVhivIiaI5ZIqDA6cIo,15155
+graphrefly/patterns/reactive_layout/__init__.py,sha256=6jn8hzU9cLn1tbE7Ot06DPtAMIQouXhqIU8RAYQ8qbo,1872
+graphrefly/patterns/reactive_layout/measurement_adapters.py,sha256=ob8k1wzVylTd2HOBFSryD7O8lsPRZnpUju9O3jRziSs,9485
+graphrefly/patterns/reactive_layout/reactive_block_layout.py,sha256=l8gn2nJwQMm_pEz8dVDt8fUrStZJmLc-gvdvFoqCb2g,14356
+graphrefly/patterns/reactive_layout/reactive_layout.py,sha256=-pqO2Cu-1MQsecxDHbb3VKJ8tj6flMzUPR0NZoIH8NA,32385
+graphrefly-0.1.0.dist-info/METADATA,sha256=PXbBAKwq5SHH8UHp3sEDdMmB5q5b93II_cHGif1SnS8,10278
+graphrefly-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+graphrefly-0.1.0.dist-info/licenses/LICENSE,sha256=gcKfYEH-2_EdipDV2fzR2hW6Sp15JX3lSyg7eS47x0U,1067
+graphrefly-0.1.0.dist-info/RECORD,,

graphrefly-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

graphrefly-0.1.0.dist-info/licenses/LICENSE

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