Skip to content

README.md

Latest commit

 

History

History
53 lines (45 loc) · 5.32 KB

README.md

File metadata and controls

53 lines (45 loc) · 5.32 KB
Raw

hypha Documentation

This directory contains public documentation for using hypha APIs, specs, runtime conventions, and extension points. It intentionally describes stable contracts rather than internal planning notes.

The published v1.0.1 user guide, complete generated API reference, FSM walkthrough, and full-system example are available at codesoul-co.github.io/Hypha. The project website is hypha.code-soul.com.

API and usage documentation

  • Complete API Reference: every public package export grouped by source module, including full declarations, imports, function parameters and returns, and class/interface members.
  • Runnable Examples: seven isolated feature entries, a 15-package tour, DomainPack compilation, Server Run submission, and custom FSM control.
  • Architecture Reference: package responsibilities, harness semantics, runtime boundaries, and extension rules.
  • Runtime Model: DomainPack, Session, Run, Event, durable orchestration, FSM, replay, audit, regression, and concurrency conventions.
  • FSM Anomaly Recovery: cross-module supervision, evidence-based convergence, bounded recovery states, cache knowledge, and module failure matrix.
  • Custom FSM Topologies: application-defined graphs, topology analysis, custom Runs, and governed owner transitions.
  • Storage Reference: document, messaging, relational, vector, and artifact storage conventions plus memory extension points.
  • Local Data Layout: ignored data/ tree for local runtime records, indexes, artifacts, and logs.
  • Framework API: TypeScript package contracts and field-level spec references.
  • HTTP API: REST endpoints, authentication, request bodies, response shapes, and SSE behavior.
  • Architecture Notes: subsystem-level architecture notes.
  • Serving Cache: exact LLM response cache middleware, key fields, policies, stores, and trace events.
  • WorkCache: event-derived typed runtime cache, recovery knowledge, tree alignments, policies, stores, and audit events.
  • Tool/MCP Architecture: governed execution, Invocation lifecycle, MCP trust, drift, and Run snapshots.
  • Execution Contracts: provider-neutral Workspace, Sandbox, Command, Store, Event, and cache-fingerprint boundaries.
  • Governed Memory: scoped records, atomic persistence and index outbox, deterministic retrieval, bounded context, external adapters, and replay/cache bindings.
  • Memory Provider Profiles: select native Redis + MongoDB, self-hosted Mem0, or managed Mem0/Vertex profiles and inspect the disabled Hindsight candidate without embedding credentials.
  • Managed Memory Migration: move legacy memory consumers to the policy, harness, event, timeout, and recovery boundary.
  • External Memory Provider Runtime: stable provider ID mapping, restart-safe persistence, cancellation, and deployment boundaries.
  • Execution Threat Model: trust boundaries, audited runtime surfaces, required controls, and residual limitations.
  • Execution Provider Matrix: provider guarantees and fail-closed capability negotiation.
  • ADRs: accepted architecture decisions.

Guides

  • Releases and npm Packages: version alignment, package verification, publication boundaries, and the standalone consumer example.
  • Upgrading Hypha: npm and source-release update, configuration migration, staging, backup, and rollback procedure.
  • Domain Packs: how to declare workflows, task schemas, tools, MCP profiles, memory profiles, policies, evaluations, regressions, and output contracts.
  • Local Development: setup, environment, commands, storage adapters, and verification checks.
  • Tool/MCP Security: trust boundaries, secrets, side effects, approval, and recovery.
  • Tool Adapter Guide: implement and register Local, HTTP, Plugin, Mock, and MCP adapters.
  • Common Utility Tools: governed JSON, text, and SHA-256 tools with limits and examples.
  • Tool/MCP Migration: move legacy handlers and MCP calls to the governed runtime.
  • Governance Examples: local Tool execution and MCP catalog/snapshot examples.
  • Capability Matrix: public surfaces and runtime guarantees.
  • Known Limitations: deliberate constraints and operational caveats.

Documentation Rules

Public docs should describe API behavior, fields, runtime conventions, package boundaries, and examples that remain valid for users of the framework. Local planning notes belong outside tracked docs.