docs: pre-merge sweep — version field, compare link, examples (#45)

Pre-merge cross-doc consistency pass:

- AUDIT.md: add `**Version:** 0.4.0` to the new entry to match the
  format of the prior streaming entry.
- CHANGELOG.md: add the `[0.4.0]` compare link at the bottom so the
  Keep-a-Changelog reference list stays complete.
- runcycles/decorator.py: extend the docstring example block with a
  callable subject/action example so the rendered Sphinx/PyPI docs
  show the new feature, not just the existing estimate/actual pattern.
- examples/decorator_usage.py: add a third decorator demonstrating
  per-call workspace + action_kind + action_name routing via lambdas.

No code or test changes. Coverage 99.38% holds, mypy clean, ruff clean.

Author: amavashev

AUDIT.md

@@ -213,6 +213,7 @@ Protocol conformance: No new endpoints or protocol changes. All reservation, com
 **Issue:** [#45](https://github.com/runcycles/cycles-client-python/issues/45)
 **Files:** `runcycles/lifecycle.py`, `runcycles/decorator.py`
 **Test files:** `tests/test_lifecycle.py`, `tests/test_decorator.py`
+**Version:** 0.4.0
 
 Widened the `@cycles` decorator to accept callables — in addition to constants — for every field that previously had to be static at decoration time. Mirrors the existing `estimate` / `actual` callable contract and re-aligns the Python client with the Java client's `@Cycles(workspace = "#workspaceId")` SpEL behavior shipped in `cycles-spring-boot-starter` 0.2.1 ([java#50](https://github.com/runcycles/cycles-spring-boot-starter/pull/50)).
 

CHANGELOG.md

@@ -120,6 +120,7 @@ Initial public release.
 
 - Comprehensive error handling and improved API model validation (#1)
 
+[0.4.0]: https://github.com/runcycles/cycles-client-python/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/runcycles/cycles-client-python/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/runcycles/cycles-client-python/compare/v0.1.3...v0.2.0
 [0.1.3]: https://github.com/runcycles/cycles-client-python/compare/v0.1.2...v0.1.3

examples/decorator_usage.py

@@ -49,6 +49,19 @@ def call_llm(prompt: str, tokens: int) -> str:
     return "Generated response for: " + prompt
 
 
+# Per-call subject / action routing via callables — resolved at reservation time
+# against the wrapped function's *args, **kwargs
+@cycles(
+    estimate=1000,
+    workspace=lambda req, workspace_id: workspace_id,
+    action_kind=lambda req, *_: f"llm.{req['provider']}",
+    action_name=lambda req, *_: req["model"],
+    client=client,
+)
+def run_request(req: dict[str, str], workspace_id: str) -> str:
+    return f"Routed {req['model']} to {workspace_id}"
+
+
 def main() -> None:
     print("Simple call:")
     result1 = simple_call()
@@ -58,6 +71,10 @@ def main() -> None:
     result2 = call_llm("Tell me a joke", tokens=200)
     print(f"  Result: {result2}")
 
+    print("\nPer-call subject/action routing:")
+    result3 = run_request({"provider": "openai", "model": "gpt-4"}, workspace_id="ws-42")
+    print(f"  Result: {result3}")
+
 
 if __name__ == "__main__":
     main()

runcycles/decorator.py

@@ -127,6 +127,17 @@ def call_llm(prompt: str) -> str:
         )
         def call_llm(prompt: str, tokens: int) -> str:
             return openai.complete(prompt, max_tokens=tokens)
+
+        # Per-call subject/action routing via callables
+        @cycles(
+            estimate=1000,
+            workspace=lambda req, workspace_id: workspace_id,
+            action_kind=lambda req, *_: f"llm.{req.provider}",
+            action_name=lambda req, *_: req.model,
+            client=my_client,
+        )
+        def run_request(req: Request, workspace_id: str) -> Response:
+            ...
     """
     unit_str = unit.value if isinstance(unit, Unit) else str(unit)