@picoflow/ezgraph 0.0.4 → 0.0.5

package/README.md

@@ -1,171 +1,122 @@
-# ezgraph
+# EZGraph
 
-ezgraph is a pre-release library of provider-neutral graph primitives built on
-LangGraph and LangChain. It is implemented as plain TypeScript and does not
-require an application framework or dependency-injection container.
+EZGraph is a pre-release TypeScript application layer for durable,
+multi-turn conversational workflows. It is built on LangGraph and LangChain,
+but gives each conversation an explicit graph, typed node state, durable session
+handling, and code-owned outcomes for validation, confirmation, and routing.
 
-Learn more, including the tutorials and developer guide, at the [EZGraph
-website](https://www.picoflow.io/ezgraph/).
+It is provider-neutral and framework-neutral: use it with the model provider
+and Node.js HTTP framework you already run.
 
-## Usage
+## What it provides
 
-~~~ts
-import { ConfigManager, GraphEngine } from "ezgraph";
-import { DemoGraph } from "./demo-graph.js";
+- Graph and node primitives for staged conversations, rather than one large
+  prompt or an implicit agent loop.
+- Per-node state, named history spaces, and typed outcomes such as `stay()`,
+  `advance()`, `finish()`, and `quit()`.
+- One versioned session document per conversation, backed by memory, SQLite,
+  MongoDB, or Azure Cosmos DB.
+- A model and tool loop that is bounded and owned by the graph, while business
+  validation and routing remain ordinary application code.
+- Provider adapters and a typed model catalog, with support for OpenAI,
+  Anthropic, Google, Azure OpenAI, and custom compatible endpoints.
 
-const config = new ConfigManager(); // reads .env, then process.env
-const engine = await GraphEngine.create({
-  configManager: config,
-  graphs: [DemoGraph],
-});
+For the product overview, tutorial, and full developer guide, visit
+[picoflow.io/ezgraph](https://www.picoflow.io/ezgraph/).
+
+## Requirements
+
+- Node.js 22.5 or later
+- TypeScript 5.x
+- A model-provider package and credentials for the provider you choose
+
+Tool handlers use method decorators. Enable `experimentalDecorators` and
+`emitDecoratorMetadata` in `tsconfig.json`, and import `reflect-metadata` once
+at the very top of your application entry point.
+
+## Install
+
+```bash
+npm install @picoflow/ezgraph
+
+# Install only the provider adapter you use.
+npm install @langchain/openai
+# or: npm install @langchain/anthropic
+# or: npm install @langchain/google
+```
+
+The provider adapters are optional peer dependencies. The published package is
+ESM; TypeScript applications should use `module` and `moduleResolution` set to
+`NodeNext`.
+
+## Start an application graph
+
+Define your graph and nodes in application code, then register the graph with a
+`GraphEngine`. The engine creates or resumes a session using the supplied
+`sessionId`.
+
+```ts
+import "reflect-metadata";
+import { GraphEngine } from "@picoflow/ezgraph";
+import { WeatherGraph } from "./weather-graph.js";
+
+const engine = await GraphEngine.create({ graphs: [WeatherGraph] });
 
 const result = await engine.run({
-  graphName: "DemoGraph",
-  userMessage: "Hello",
-});
-~~~
-
-Graph and node IDs default to their class names, so existing declarations need
-no identity boilerplate. If a class is renamed, preserve its persisted identity
-with an override:
-
-~~~ts
-export class MyWeatherNode extends GraphNode<DemoGraphState> {
-  static override id() {
-    return "WeatherNode";
-  }
-}
-~~~
-
-References that intentionally select a node identity should likewise use
-`WeatherNode.id()` rather than `WeatherNode.name`, including the initial node
-passed to `createGraphStateAnnotation`. Existing `nodes(...)`, `registerTurns(...)`,
-`addEdge(...)`, and `advance(...)` calls remain unchanged. `branchBy(...)`
-cases use `{ when: selector, routeTo: destination }` objects.
-
-Every graph has an independent persisted schema version. Version 1 is the
-default; set `schemaVersion` and provide ordered migrations in the graph
-definition only when its persisted state shape changes.
-
-Conversational stages extend `ConversationNode` and return semantic outcomes
-instead of manually coordinating graph protocol fields:
-
-~~~ts
-protected nextStep(state, context, conversation) {
-  if (conversation.quitRequested) return this.quit(conversation);
-  if (context.complete) {
-    return this.advance(NextNode, conversation)
-      .withState({ value: context.value });
-  }
-  return this.stay(conversation).withState({ value: context.value });
-}
-~~~
-
-Use `finish(response, conversation)` for terminal responses. Outcome builders
-automatically coordinate history, tokens, response, input consumption, and the
-persisted resume node. `toolResult(output).withContext(...)` provides typed
-per-turn tool effects, and `branchBy(...)` keeps conditional
-topology in the graph without a repetitive `route()` method. See
-`docs/conversation-node-outcomes.md` in the source repository for the complete
-contract.
-
-For conversation graphs, call `graph.configAutoRoute()` to route semantic
-outcomes automatically: `stay()` ends the current invocation, `advance()`
-continues at its target, `quit()` continues at `TerminateSessionNode`, and
-`finish()` ends it. Use `.via(WorkerNode)` to run a registered worker first
-without changing the outcome's durable `currentNode`. `branchBy(SourceNode,
-...)` remains available when a source needs explicit topology and takes
-precedence over automatic routing for that source.
-
-`GraphEngine` uses in-memory session persistence by default, so the shorter
-`new GraphEngine().registerGraph([DemoGraph])` form works without configuration.
-Set `SESSION_STORE` to `sqlite`, `mongodb`, or `cosmos` when durable persistence
-is needed.
-
-## Model catalog
-
-Built-in models use `ModelCatalog.model`, which correlates each model ID with its legal
-parameters at compile time and validates the same contract at runtime:
-
-~~~ts
-import { ModelCatalog } from "ezgraph";
-
-const llmConfig = ModelCatalog.model("openai:gpt-5.4", {
-  retries: 3,
-  reasoningEffort: "medium",
-  forceToolCalls: true,
-});
-~~~
-
-For a model released after the installed EZGraph version, load an application
-JSON catalog at startup and use its resolver. Catalog construction validates
-the profile, JSON Schema, parameter mappings, provider/model relationship, and
-references. `catalog.model(...)` then validates parameters and returns a
-branded runtime configuration; an arbitrary object cannot bypass the catalog.
-
-~~~ts
-import modelCatalogJson from "./model-catalog.json" with { type: "json" };
-import { ModelCatalog } from "ezgraph";
-
-const catalog = ModelCatalog.create(modelCatalogJson);
-const llmConfig = catalog.model("openai:future-model", {
-  retries: 3,
-  reasoningEffort: "medium",
-});
-~~~
-
-The complete JSON format is published as
-`ezgraph/model-catalog.schema.json`. Built-in entries cannot be replaced by an
-application catalog. A full node model configuration replaces the graph model;
-`{ params: { temperature: 0.5 } }` patches the current model and `null` removes
-an inherited optional parameter.
-
-Providers absent from EZGraph and LangChain require application code because
-JSON cannot safely contain constructors or credentials. Register an initializer
-and pass the registry when creating the catalog:
-
-~~~ts
-import { ModelCatalog, ModelProviderRegistry } from "ezgraph";
-
-const providers = ModelProviderRegistry.create().register("glm", {
-  initialize({ model, options }) {
-    return {
-      model,
-      options: {
-        modelProvider: "openai",
-        ...options,
-        apiKey: process.env.GLM_API_KEY,
-        configuration: { baseURL: "https://api.z.ai/api/paas/v4" },
-      },
-      cacheKey: JSON.stringify({ provider: "glm", model, options }),
-    };
-  },
+  graphName: "WeatherGraph",
+  sessionId: "customer-123",
+  userMessage: "I need the weather in Seattle",
 });
 
-const catalog = ModelCatalog.create(modelCatalogJson, { providers });
-~~~
+// { status, body, session }
+```
+
+`GraphEngine.create()` reads `.env` and process environment values. Model
+credentials stay with the provider you configure; EZGraph does not require an
+EZGraph account or runtime key.
+
+For a complete two-stage graph, including state, a tool handler, explicit
+outcomes, and graph registration, follow the
+[Get started tutorial](https://www.picoflow.io/ezgraph/tutorial/).
+
+## Persistence and configuration
+
+The default `SESSION_STORE=memory` is useful for local development. Select a
+durable store when conversations must resume across process restarts or
+instances:
+
+```dotenv
+# memory (default), sqlite, mongodb, or cosmos
+SESSION_STORE=sqlite
+SQLITE_DB_PATH=./data/sessions.sqlite
+
+# Set the credential for the model provider you use.
+OPENAI_API_KEY=...
+```
 
-The catalog rejects an unregistered custom provider during startup. Provider
-credentials are initializer concerns and are never persisted in model metadata.
+For MongoDB, configure `MONGODB_URL`, `MONGODB_NAME`, and
+`MONGODB_COLLECTION`. For Cosmos DB, use the Cosmos settings described in the
+[developer guide](https://www.picoflow.io/ezgraph/docs/developer-guide/).
 
-## Development
+The [EZGraph demo application](https://github.com/picoflowio/ezgraph-demo)
+shows a NestJS + Fastify service with QuoteGraph, a LangGraph comparison, and a
+copyable [`.env.example`](https://github.com/picoflowio/ezgraph-demo/blob/main/.env.example).
 
-From the repository root:
+## Learn more
 
-~~~sh
-npm ci
-npm run build:npmlib
-npm run build:locallib
-~~~
+- [Get started tutorial](https://www.picoflow.io/ezgraph/tutorial/)
+- [Developer guide](https://www.picoflow.io/ezgraph/docs/developer-guide/)
+- [QuoteGraph walkthrough](https://www.picoflow.io/ezgraph/quote-graph/)
+- [EZGraph compared with direct LangGraph](https://www.picoflow.io/ezgraph/compare/langgraph/)
 
-`build:npmlib` creates `staging/npm`, the publishable ESM package. Its bundle
-is minified, keeps public runtime names, and deliberately contains no source
-map or source files. `build:locallib` creates `staging/lib`, a local-only package
-that retains the framework TypeScript source and an unbundled, source-mapped
-runtime for debugging through the sibling demo. Re-run `build:locallib` after
-framework changes.
+## License
 
-## Distribution status
+EZGraph is proprietary software distributed under the
+[EZGraph Commercial Runtime License](https://www.picoflow.io/ezgraph/license/).
+Personal use, commercial SaaS, internal enterprise production, client work,
+and closed-source applications are permitted with no EZGraph runtime fee or
+license key. Optional support is separate; an active support subscription
+includes the private source and debug package.
 
-EZGraph is distributed under the EZGraph Commercial Runtime License. See
-`LICENSE.md` in the published package for the applicable production-use terms.
+See the [license page](https://www.picoflow.io/ezgraph/license/) for the
+applicable production-use terms.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@picoflow/ezgraph",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "Provider-neutral graph primitives built on LangGraph and LangChain.",
   "type": "module",
   "main": "./dist/index.js",