feat: reorganize core

Author: brian14708

README.md

@@ -8,7 +8,7 @@ Duron is a Python library that makes async work _replayable_. You can pause, res
 - 🧵 **Async-first** — Write `async def` functions and orchestrate them with familiar `await` syntax.
 - 🔍 **Typed & traceable** — Decorators capture type hints so inputs and outputs serialize cleanly.
 - 🗄️ **Storage-agnostic** — Start with file-based logging or plug in your own backend to match your stack.
-- 🚀 **Drop-in ready** — Works in CLI tools, web backends, or long-lived agents—no special runtime required.
+- 🚀 **Drop-in ready** — Works in CLI tools, web backends, or long-lived agents—no special runtime or extra dependencies required.
 
 ## Install
 

docs/index.md

@@ -0,0 +1,64 @@
+---
+title: Duron
+hide:
+  - toc
+  - navigation
+---
+
+## Install
+
+Duron requires **Python 3.10+**.
+
+```bash
+pip install git+https://github.com/brian14708/duron.git
+```
+
+## Quickstart
+
+Duron defines two kinds of functions:
+
+- `@duron.durable` — deterministic orchestration. It replays from logs, ensuring that control flow only advances when every prior step is known.
+- `@duron.effect` — side effects. Wrap anything that touches the outside world (APIs, databases, file I/O). Duron records its return value so it runs once per unique input.
+
+```python
+import asyncio
+import random
+from pathlib import Path
+
+import duron
+from duron.contrib.storage import FileLogStorage
+
+
+@duron.effect
+async def work(name: str) -> str:
+    print("⚡ Preparing to greet...")
+    await asyncio.sleep(2)  # Simulate I/O
+    print("⚡ Greeting...")
+    return f"Hello, {name}!"
+
+
+@duron.effect
+async def generate_lucky_number() -> int:
+    print("⚡ Generating lucky number...")
+    await asyncio.sleep(1)  # Simulate I/O
+    return random.randint(1, 100)
+
+
+@duron.durable
+async def greeting_flow(ctx: duron.Context, name: str) -> str:
+    message, lucky_number = await asyncio.gather(
+        ctx.run(work, name), ctx.run(generate_lucky_number)
+    )
+    return f"{message} Your lucky number is {lucky_number}."
+
+
+async def main():
+    async with greeting_flow.invoke(FileLogStorage(Path("log.jsonl"))) as job:
+        await job.start("Alice")
+        result = await job.wait()
+    print(result)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```

docs/reference/contrib.md

@@ -0,0 +1,6 @@
+# `duron.contrib` module
+
+## ::: duron.contrib
+
+    options:
+        show_submodules: true

examples/hello_world.py

@@ -30,7 +30,7 @@ async def generate_lucky_number() -> int:
     return random.randint(1, 100)
 
 
-@duron.effect(checkpoint=True, initial=lambda: 0, reducer=int.__add__)
+@duron.effect(stateful=True, initial=lambda: 0, reducer=int.__add__)
 async def count_up(count: int, target: int) -> AsyncGenerator[int, int]:
     await asyncio.sleep(0.5)
     while count < target:

mkdocs.yaml

@@ -3,13 +3,15 @@ site_url: "https://brian14708.github.io/duron"
 repo_url: "https://github.com/brian14708/duron"
 repo_name: "brian14708/duron"
 nav:
-  - index.md
+  - Home:
+      - index.md
   - Reference:
       - reference/duron.md
       - reference/log.md
       - reference/codec.md
       - reference/tracing.md
       - reference/typing.md
+      - reference/contrib.md
   - Trace UI: https://brian14708.github.io/duron/trace-ui/
 
 theme:
@@ -40,6 +42,7 @@ plugins:
             show_source: false
             show_submodules: false
             show_attribute_values: false
+            separate_signature: true
             merge_init_into_class: true
             members: true
           inventories:

src/duron/__init__.py

@@ -1,10 +1,12 @@
 from duron._core.config import set_config as set_config
 from duron._core.context import Context as Context
+from duron._core.invoke import DurableRun as DurableRun
 from duron._core.signal import Signal as Signal
 from duron._core.signal import SignalInterrupt as SignalInterrupt
 from duron._core.signal import SignalWriter as SignalWriter
 from duron._core.stream import Stream as Stream
 from duron._core.stream import StreamClosed as StreamClosed
+from duron._core.stream import StreamOp as StreamOp
 from duron._core.stream import StreamWriter as StreamWriter
 from duron._decorator.durable import DurableFn as DurableFn
 from duron._decorator.durable import durable as durable

src/duron/_core/config.py

@@ -23,5 +23,10 @@ def set_config(
     *,
     codec: Codec | None = None,
 ) -> None:
+    """Set global configuration for Duron.
+
+    Args:
+        codec: The codec to use for serializing and deserializing data.
+    """
     if codec is not None:
         config.codec = codec