Skip to content

README.md

Latest commit

 

History

History
47 lines (30 loc) · 3.58 KB

README.md

File metadata and controls

47 lines (30 loc) · 3.58 KB
Raw

harpua

A reusable toolkit for building LangGraph agents with NestJS: graphs assembled from plain Nest providers, typed edge lists, pluggable checkpointers, streaming, human-in-the-loop interrupts, and OpenTelemetry tracing — plus companion packages for testing and prebuilt agent tools.

Packages

  • @harpua/langgraph — the core framework. Nodes are ordinary @Injectable providers reusable across graphs; graphs are typed class-ref edge lists compiled and validated at bootstrap; tools bind through DI (or mount as raw LangChain tool instances); checkpointing supports memory, Postgres, SQLite, MongoDB, and Redis via optional peers; the injected facade covers invoke, all stream modes, interrupt/resume, and checkpoint time travel. Emits OpenTelemetry spans when an SDK is registered (Langfuse-compatible via @langfuse/otel). Ships its agent skills in the tarball.
  • @harpua/langgraph-testing — deterministic testing helpers: scripted/rule-based fake chat models, stream collectors, interrupt assertions, a Nest testing-module harness, and an injectable fixed clock.
  • @harpua/agent-tools — framework-agnostic prebuilt LangChain tools (currently the Anthropic-style think scratchpad tool). Depends only on @langchain/core and zod; works with any LangGraph app and drops straight into @harpua/langgraph graphs.
  • packages/typescript-config, packages/eslint-config — shared build config (private).

Proof harness

  • apps/api — a NestJS 11 app exercising the toolkit end-to-end: an agentic chat graph with a deterministic mock LLM (no API keys), tool calls through DI, approval interrupts with resume, thread persistence, an SSE streaming endpoint, and a CLI REPL (pnpm --filter @harpua/api chat). It is a test bed, not the product.

Agent skills

@harpua/langgraph ships agentskills.io-format recipes under skills/graph-operations/ covering tools, nodes, graphs, testing, debugging (including Postgres/Redis checkpoint time travel), human-in-the-loop, streaming, checkpointers, and observability. The format is an open standard — the same skills work in Claude Code, OpenAI Codex, and other compatible agents. See the package README for wiring. This repo itself exposes its skills to both: .claude/skills/ is the source of truth and .agents/skills/ symlinks into it (with AGENTS.md → CLAUDE.md for Codex contributors).

Requirements

  • Node.js >= 20 (developed against v23.10.0)
  • pnpm 9.15.0 (packageManager pinned in package.json)

Usage

pnpm install
pnpm build
pnpm dev
pnpm lint
pnpm test

Tasks run through Turborepo; scope with --filter (e.g. pnpm turbo test --filter @harpua/langgraph).

Releases

Publishing is automated with changesets:

  • Every change to a publishable package ships with a changeset — run pnpm exec changeset, pick the packages and bump, and commit the generated file alongside your change. (0.x: breaking = minor, feature/fix = patch.)
  • A Version Packages PR is the publish button. The release workflow keeps it up to date; merging it bumps versions, writes changelogs, and publishes to npm. No other action publishes.
  • Auth is npm trusted publishing via GitHub OIDC — there are no npm tokens in the repo or CI.

License

MIT for the publishable packages (@harpua/langgraph, @harpua/langgraph-testing, @harpua/agent-tools). See LICENSE.