Merge pull request #46 from madeinplutofabio/phase-3.A.3/pr-g-post-publish-front-door-sync

docs(phase-3.A.3): sync front-door docs to ncp-langgraph v0.1.0 (PR G)

Author: madeinplutofabio

README.md

@@ -15,14 +15,14 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/madeinplutofabio/neural-computation-protocol/actions/workflows/validate.yml"><img alt="CI" src="https://github.com/madeinplutofabio/neural-computation-protocol/actions/workflows/validate.yml/badge.svg" /></a>&nbsp;<a href="https://crates.io/crates/ncp-runtime"><img alt="ncp-runtime on crates.io" src="https://img.shields.io/crates/v/ncp-runtime?logo=rust&label=ncp-runtime" /></a>&nbsp;<a href="https://crates.io/crates/ncp-mcp-server"><img alt="ncp-mcp-server on crates.io" src="https://img.shields.io/crates/v/ncp-mcp-server?logo=rust&label=ncp-mcp-server" /></a>&nbsp;<a href="https://docs.rs/ncp-runtime"><img alt="docs.rs" src="https://img.shields.io/docsrs/ncp-runtime" /></a>&nbsp;<a href="https://github.com/madeinplutofabio/neural-computation-protocol/blob/main/rust-toolchain.toml"><img alt="MSRV" src="https://img.shields.io/crates/msrv/ncp-runtime" /></a>&nbsp;<a href="https://opensource.org/licenses/Apache-2.0"><img alt="License" src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" /></a>&nbsp;<a href="https://doi.org/10.5281/zenodo.19570209"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.19570209.svg?v=1" alt="DOI"></a>&nbsp;<a href="https://github.com/madeinplutofabio/neural-computation-protocol/releases"><img alt="Release" src="https://img.shields.io/github/v/release/madeinplutofabio/neural-computation-protocol?display_name=tag&include_prereleases" /></a>&nbsp;<a href="https://github.com/madeinplutofabio/neural-computation-protocol/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/madeinplutofabio/neural-computation-protocol?style=social" /></a>
+  <a href="https://github.com/madeinplutofabio/neural-computation-protocol/actions/workflows/validate.yml"><img alt="CI" src="https://github.com/madeinplutofabio/neural-computation-protocol/actions/workflows/validate.yml/badge.svg" /></a>&nbsp;<a href="https://crates.io/crates/ncp-runtime"><img alt="ncp-runtime on crates.io" src="https://img.shields.io/crates/v/ncp-runtime?logo=rust&label=ncp-runtime" /></a>&nbsp;<a href="https://crates.io/crates/ncp-mcp-server"><img alt="ncp-mcp-server on crates.io" src="https://img.shields.io/crates/v/ncp-mcp-server?logo=rust&label=ncp-mcp-server" /></a>&nbsp;<a href="https://pypi.org/project/ncp-langgraph/"><img alt="ncp-langgraph on PyPI" src="https://img.shields.io/pypi/v/ncp-langgraph?logo=python&label=ncp-langgraph" /></a>&nbsp;<a href="https://docs.rs/ncp-runtime"><img alt="docs.rs" src="https://img.shields.io/docsrs/ncp-runtime" /></a>&nbsp;<a href="https://github.com/madeinplutofabio/neural-computation-protocol/blob/main/rust-toolchain.toml"><img alt="MSRV" src="https://img.shields.io/crates/msrv/ncp-runtime" /></a>&nbsp;<a href="https://opensource.org/licenses/Apache-2.0"><img alt="License" src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" /></a>&nbsp;<a href="https://doi.org/10.5281/zenodo.19570209"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.19570209.svg?v=1" alt="DOI"></a>&nbsp;<a href="https://github.com/madeinplutofabio/neural-computation-protocol/releases"><img alt="Release" src="https://img.shields.io/github/v/release/madeinplutofabio/neural-computation-protocol?display_name=tag&include_prereleases" /></a>&nbsp;<a href="https://github.com/madeinplutofabio/neural-computation-protocol/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/madeinplutofabio/neural-computation-protocol?style=social" /></a>
 </p>
 
 ---
 
 **Docs:** [Adoption guide](https://github.com/madeinplutofabio/neural-computation-protocol/blob/main/docs/ADOPTION_GUIDE.md) · [Benchmarks](https://github.com/madeinplutofabio/neural-computation-protocol/blob/main/BENCHMARK.md) · [Cost model](https://github.com/madeinplutofabio/neural-computation-protocol/blob/main/COST_MODEL.md) · [Roadmap](https://github.com/madeinplutofabio/neural-computation-protocol/blob/main/docs/ROADMAP.md) · [Spec](https://github.com/madeinplutofabio/neural-computation-protocol/blob/main/spec/ncp-v0.2.3.md) · [Contributing](https://github.com/madeinplutofabio/neural-computation-protocol/blob/main/CONTRIBUTING.md) · [Security](https://github.com/madeinplutofabio/neural-computation-protocol/blob/main/SECURITY.md)
 
-**Status:** Protocol v0.2.3 + validator are stable. Reference runtime is available via [GitHub Releases](https://github.com/madeinplutofabio/neural-computation-protocol/releases/latest), [GHCR](https://github.com/madeinplutofabio/neural-computation-protocol/pkgs/container/ncp), and [crates.io](https://crates.io/crates/ncp-runtime) (Phase 3A.1 complete). [`ncp-mcp-server v0.1.0`](https://crates.io/crates/ncp-mcp-server) is live on crates.io (Phase 3A.2 complete). Next adoption work: LangGraph wrapper + SDKs.
+**Status:** Protocol v0.2.3 + validator are stable. Reference runtime is available via [GitHub Releases](https://github.com/madeinplutofabio/neural-computation-protocol/releases/latest), [GHCR](https://github.com/madeinplutofabio/neural-computation-protocol/pkgs/container/ncp), and [crates.io](https://crates.io/crates/ncp-runtime) (Phase 3A.1 complete). [`ncp-mcp-server v0.1.0`](https://crates.io/crates/ncp-mcp-server) is live on crates.io (Phase 3A.2 complete). [`ncp-langgraph v0.1.0`](https://pypi.org/project/ncp-langgraph/0.1.0/) is live on PyPI (Phase 3A.3 complete). Next adoption work: brick packs + SDKs.
 
 ## What is NCP?
 
@@ -214,7 +214,56 @@ Each `--graph` becomes one MCP tool. The host sends a `tools/call`; NCP runs the
 
 For ready-to-customize examples, see [examples/mcp/](https://github.com/madeinplutofabio/neural-computation-protocol/tree/main/examples/mcp).
 
-For the in-development LangGraph wrapper (Phase 3A.3), see [`docs/LANGGRAPH_ADAPTER.md`](https://github.com/madeinplutofabio/neural-computation-protocol/blob/main/docs/LANGGRAPH_ADAPTER.md).
+---
+
+## Use NCP from LangGraph (Python)
+
+If your agent stack is Python and uses [LangGraph](https://github.com/langchain-ai/langgraph), wrap any NCP graph as a LangGraph node with `ncp-langgraph`. The adapter spawns `ncp-mcp-server` under the hood; you write idiomatic LangGraph `StateGraph` code.
+
+Install both:
+
+```bash
+cargo install ncp-mcp-server --version 0.1.0 --locked
+python -m pip install ncp-langgraph
+```
+
+Minimal LangGraph integration:
+
+```python
+from typing import Any, TypedDict
+
+from langgraph.graph import END, START, StateGraph
+
+from ncp_langgraph import NCPNode
+
+
+class State(TypedDict, total=False):
+    company_url: str
+    qualification: dict[str, Any]
+    ncp_trace: dict[str, Any]
+
+
+qualify_lead = NCPNode.from_subprocess(
+    graph="/abs/path/to/lead-qualification.yaml",
+    brick_dir="/abs/path/to/bricks",
+    output_key="qualification",
+    timeout=30.0,
+)
+
+builder = StateGraph(State)
+builder.add_node("qualify_lead", qualify_lead)
+builder.add_edge(START, "qualify_lead")
+builder.add_edge("qualify_lead", END)
+compiled = builder.compile()
+
+result = compiled.invoke({"company_url": "https://example.com"})
+# result["qualification"] -- the NCP graph's output_json
+# result["ncp_trace"]     -- {"result_type", "trace_id", "trace_path"}
+```
+
+`NCPNode.__call__` returns a partial state update; LangGraph merges it according to your `StateGraph`'s schema + reducers. State is not mutated.
+
+For ready-to-run examples, see [examples/langgraph/](https://github.com/madeinplutofabio/neural-computation-protocol/tree/main/examples/langgraph). For the full design contract (locked signature, exception model, v0.1.0 limitations), see [`docs/LANGGRAPH_ADAPTER.md`](https://github.com/madeinplutofabio/neural-computation-protocol/blob/main/docs/LANGGRAPH_ADAPTER.md).
 
 ---
 

docs/ADOPTION_GUIDE.md

@@ -106,6 +106,57 @@ For host config examples and smoke-test recipes, see [`examples/mcp/README.md`](
 
 ---
 
+## Use NCP graphs in LangGraph workflows
+
+If your agent stack is Python and uses [LangGraph](https://github.com/langchain-ai/langgraph), the `ncp-langgraph` adapter lets you wrap an NCP graph as a LangGraph node directly. Same NCP graph, no glue code; you write idiomatic LangGraph `StateGraph` code.
+
+Install both:
+
+```bash
+cargo install ncp-mcp-server --version 0.1.0 --locked
+python -m pip install ncp-langgraph
+```
+
+Minimal integration:
+
+```python
+from typing import Any, TypedDict
+
+from langgraph.graph import END, START, StateGraph
+
+from ncp_langgraph import NCPNode
+
+
+class State(TypedDict, total=False):
+    company_url: str
+    qualification: dict[str, Any]
+    ncp_trace: dict[str, Any]
+
+
+qualify_lead = NCPNode.from_subprocess(
+    graph="/abs/path/to/graph.yaml",
+    brick_dir="/abs/path/to/bricks",
+    output_key="qualification",
+    timeout=30.0,
+)
+
+builder = StateGraph(State)
+builder.add_node("qualify_lead", qualify_lead)
+builder.add_edge(START, "qualify_lead")
+builder.add_edge("qualify_lead", END)
+compiled = builder.compile()
+
+result = compiled.invoke({"company_url": "https://example.com"})
+```
+
+`NCPNode.__call__` returns a partial state update; LangGraph merges it according to your `StateGraph`'s schema + reducers. State is not mutated.
+
+Use this when an agent repeats a workflow often enough that it should not re-plan the same steps in the LLM conversation every time. Good fits include lead qualification, support-ticket routing, document triage, content research pipelines, code-change risk review, and data normalization before an agent acts. (Same use-case family as the MCP integration above; pick whichever surface your stack already has.)
+
+For ready-to-run examples, see [`examples/langgraph/README.md`](../examples/langgraph/README.md). For the binding design contract, see [`docs/LANGGRAPH_ADAPTER.md`](LANGGRAPH_ADAPTER.md).
+
+---
+
 ## 3) Understand the moving parts (2 minutes)
 
 - **Brick**: a sandboxed WASM module that implements the NCP ABI (`alloc/free/invoke`).
@@ -266,13 +317,15 @@ It **does** replace or harden:
 
 ## 10) Production readiness (current scope and what’s next)
 
-The reference runtime’s distribution channels are live as of Phase 3A.1 — available
+The reference runtime's distribution channels are live as of Phase 3A.1, available
 through [GitHub Releases](https://github.com/madeinplutofabio/neural-computation-protocol/releases/latest),
 [GHCR](https://github.com/madeinplutofabio/neural-computation-protocol/pkgs/container/ncp),
 and [crates.io](https://crates.io/crates/ncp-runtime). The MCP adapter is live as
-of Phase 3A.2 — install with `cargo install ncp-mcp-server --locked` (see
-[crates.io](https://crates.io/crates/ncp-mcp-server)). Together they’re a
-strong base for evaluation and internal pilots:
+of Phase 3A.2, install with `cargo install ncp-mcp-server --version 0.1.0 --locked`
+(see [crates.io](https://crates.io/crates/ncp-mcp-server)). The LangGraph adapter
+is live as of Phase 3A.3, install with `python -m pip install ncp-langgraph` (see
+[PyPI](https://pypi.org/project/ncp-langgraph/0.1.0/)). Together they're a strong
+base for evaluation and internal pilots:
 - deterministic routing + mapping
 - sandboxed WASM invokes
 - trace output and safety budgets
@@ -284,9 +337,10 @@ But **production hardening** typically needs:
 - real LLM adapters + token accounting
 - threat model + security review checklist
 
-Next adoption work focuses on the LangGraph wrapper, brick packs, and
-SDKs (Phase 3A.3–3A.5; the MCP adapter shipped as Phase 3A.2). Deeper
-hardening lands in Phase 3C, and the production wrapper in Phase 4. See
+Next adoption work focuses on brick packs and SDKs (Phase 3A.4–3A.5; the
+MCP adapter shipped as Phase 3A.2 and the LangGraph adapter as Phase
+3A.3). Deeper hardening lands in Phase 3C, and the production wrapper in
+Phase 4. See
 [`docs/ROADMAP.md`](https://github.com/madeinplutofabio/neural-computation-protocol/blob/main/docs/ROADMAP.md)
 for the full track breakdown.
 

docs/INSTALL.md

@@ -164,6 +164,34 @@ For host configuration and smoke-test examples, see
 
 ---
 
+## Install the LangGraph adapter
+
+`ncp-langgraph` is a separate published Python package that lets you
+wrap any NCP graph as a LangGraph node. It spawns `ncp-mcp-server`
+under the hood, so install both:
+
+```bash
+# 1. The NCP MCP adapter binary (Rust crate)
+cargo install ncp-mcp-server --version 0.1.0 --locked
+
+# 2. The Python adapter (this package)
+python -m pip install ncp-langgraph
+
+# Or pin to a specific version for reproducibility
+python -m pip install ncp-langgraph==0.1.0
+```
+
+`ncp-langgraph` does NOT bundle the `ncp-mcp-server` binary; the
+binary is distributed separately as a Rust crate. Keep it on `PATH`
+or pass its absolute path via `NCPNode.from_subprocess(binary=...)`.
+
+For end-to-end examples (LangGraph `StateGraph` with one `NCPNode`),
+see [`examples/langgraph/README.md`](../examples/langgraph/README.md).
+For the binding design contract, see
+[`docs/LANGGRAPH_ADAPTER.md`](LANGGRAPH_ADAPTER.md).
+
+---
+
 ## Next steps
 
 - **Adopting NCP in your stack:** [`docs/ADOPTION_GUIDE.md`](ADOPTION_GUIDE.md)

docs/LANGGRAPH_ADAPTER.md

@@ -625,7 +625,7 @@ Run end-to-end from a workspace clone:
 
 ```bash
 cargo install ncp-mcp-server --version 0.1.0 --locked
-python -m pip install -e python/ncp-langgraph
+python -m pip install ncp-langgraph
 python -m pip install -r examples/langgraph/requirements.txt
 python examples/langgraph/lead_qualification_agent.py
 ```

docs/ROADMAP.md

@@ -187,7 +187,7 @@ This section reflects the latest released state. Keep it honest and specific; up
 
 ### 3A.3 LangGraph wrapper (Python)
 
-**Status:** In progress (Phase 3A.3). Design locked in [`docs/LANGGRAPH_ADAPTER.md`](LANGGRAPH_ADAPTER.md); implementation in flight.
+**Status:** ✅ Complete (shipped 2026-05-29, [`ncp-langgraph v0.1.0`](https://pypi.org/project/ncp-langgraph/0.1.0/) on PyPI). Design locked in [`docs/LANGGRAPH_ADAPTER.md`](LANGGRAPH_ADAPTER.md); publish ceremony documented in [`docs/PUBLISHING.md`](PUBLISHING.md) "Python adapter publish (`ncp-langgraph`)".
 
 **Deliverables**
 - Python package that exposes an `NCPNode` usable inside LangGraph

examples/langgraph/README.md

@@ -7,7 +7,7 @@
 
 This directory shows how to drop an [NCP] graph into a
 [LangGraph] workflow using
-[`ncp-langgraph`](https://github.com/madeinplutofabio/neural-computation-protocol/tree/main/python/ncp-langgraph),
+[`ncp-langgraph`](https://pypi.org/project/ncp-langgraph/),
 the Python adapter that wraps `ncp-mcp-server` as a LangGraph node.
 
 **One NCP graph = one LangGraph node.**
@@ -63,15 +63,6 @@ spawns as a subprocess.
 
 ### 2. Install the Python adapter
 
-Until `ncp-langgraph` v0.1.0 is published to PyPI in Phase 3A.3 PR F,
-install editable from a workspace clone:
-
-```bash
-python -m pip install -e python/ncp-langgraph
-```
-
-After publish, the same package will be installable from PyPI directly:
-
 ```bash
 python -m pip install ncp-langgraph
 ```

examples/langgraph/lead_qualification_agent.py

@@ -36,8 +36,7 @@
   echo-pipeline graph + bricks via relative paths from this file.
 - ``cargo install ncp-mcp-server --version 0.1.0 --locked`` (or build
   from source).
-- ``pip install -e python/ncp-langgraph`` (or
-  ``pip install ncp-langgraph`` once published to PyPI in PR F).
+- ``python -m pip install ncp-langgraph``.
 - See ``examples/langgraph/requirements.txt`` for the Python deps.
 """
 

examples/langgraph/requirements.txt

@@ -3,20 +3,12 @@
 #
 # Python dependencies for examples/langgraph/lead_qualification_agent.py.
 #
-# Note: ncp-langgraph is intentionally NOT listed here. It must be
-# installed separately because Phase 3A.3 PR E lands before PyPI
-# publish (PR F), and the editable workspace install is `0.1.0.dev0`
-# which would not satisfy a `>=0.1.0` pin. Install it explicitly:
+# Note: ncp-langgraph is intentionally NOT listed here because the
+# README installs it explicitly in a separate step:
 #
-#   # Pre-publish (from workspace clone):
-#   python -m pip install -e python/ncp-langgraph
-#
-#   # Post-publish:
 #   python -m pip install ncp-langgraph
 #
 # Also note: `cargo install ncp-mcp-server --version 0.1.0 --locked`
-# is a separate prerequisite (the Rust binary that ncp-langgraph
-# spawns); it is not a pip dependency. The version is pinned so the
-# example stays reproducible against ncp-langgraph v0.1.x.
+# is a separate prerequisite.
 
 langgraph>=1.0.0,<2.0.0