Skip to content

Rewrite README as a capability tour - #19

Open
twist900 wants to merge 1 commit into
freshaengineering:mainfrom
twist900:readme-capability-tour
Open

Rewrite README as a capability tour#19
twist900 wants to merge 1 commit into
freshaengineering:mainfrom
twist900:readme-capability-tour

Conversation

@twist900

@twist900 twist900 commented Jul 8, 2026

Copy link
Copy Markdown
Collaborator

Why

Follow-up to #17 / #18: this commit was part of #18 but was not included in the merge, so the README on main still documents the pre-#17 library — the strongest new capabilities (durable execution, stream modes, prebuilt agent, long-term memory, time travel) are invisible, and a few documented facts are now stale (checkpointer behaviour callbacks, provider callbacks).

What

  • Hero example is now the one-call LangEx.Prebuilt.agent/1 with the outputs a reader cares about; the hand-wired loop moves to Quick Start as the "full control" path.
  • Old "Features" list replaced by a "What it can do" tour: nine outcome-named sections (Survive crashes, Pause for humans, Rewind and fork, Stream at the granularity you need, Remember across conversations, Fan out, fan in, Absorb failure, Compose graphs from graphs, Watch every run), each a 4-10 line snippet plus one line of prose. Option-level detail defers to hexdocs and the runnable examples/scripts.
  • Corrected facts: LangEx.Checkpointer callbacks now include delete_thread/1, custom providers should implement chat_with_usage/2 for usage accounting, added optional OpenTelemetry deps to Installation, license badge points at this repo.
  • Untouched: "Why LangEx?", Quick Start example, Configuration, Examples table.

How

Documentation-only change — no code. Snippets were written against the shipped APIs (all covered by the existing test suite) and total length is 279 lines vs 263 before.

QA instructions

  1. Read README.md top to bottom — each snippet should be understandable without opening the docs.
  2. Spot-check snippet APIs against the library (all exist on main): Prebuilt.agent/1, LangEx.stream(..., modes: [...]), LangEx.Store.put/3, Graph.add_node/4 with retry:/cache:/defer:, LangEx.get_state_history/2, Graph.to_mermaid/1.
  3. mix test still green (docs-only, but the suite runs in CI anyway).

Made with Cursor

Lead with the one-call prebuilt agent, then present each capability
(crash recovery, human-in-the-loop, time travel, stream modes,
long-term memory, fan-out/fan-in, node resilience, subgraphs,
observability) as a short intuition-building snippet, deferring
option-level detail to hexdocs and the runnable example scripts.

Co-authored-by: Cursor <cursoragent@cursor.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant