Skip to content

Commit d465bbf

Browse files
erwinmsmitherwinmsmith
committed
merge dev-merge: publish expanded API documentation
# Conflicts: # examples/release-agent/src/package-tour.ts
2 parents 93f2fca + 16a2758 commit d465bbf

761 files changed

Lines changed: 63249 additions & 285 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.md‎

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -125,14 +125,14 @@ The latest three-way comparison was run against Hypha `main@ef33263` with one tr
125125
(385 tasks total). The base model was `deepseek-v4-flash`. Hypha is the framework result and
126126
Direct is the direct model-call baseline. Neither arm reported a system error.
127127

128-
| Benchmark | Tasks | Hypha | Direct |
129-
| --------- | ----: | ----: | ------: |
130-
| Mock | 10 | 0.800 (8/10) | 0.800 (8/10) |
131-
| Airline | 50 | 0.880 (44/50) | 0.900 (45/50) |
132-
| Retail | 114 | 0.912 (104/114) | 0.895 (102/114) |
133-
| Telecom | 114 | 0.605 (69/114) | 0.588 (67/114) |
134-
| Banking knowledge | 97 | 0.206 (20/97) | 0.196 (19/97) |
135-
| **Total** | **385** | **0.636 (245/385)** | **0.626 (241/385)** |
128+
| Benchmark | Tasks | Hypha | Direct |
129+
| ----------------- | ------: | ------------------: | ------------------: |
130+
| Mock | 10 | 0.800 (8/10) | 0.800 (8/10) |
131+
| Airline | 50 | 0.880 (44/50) | 0.900 (45/50) |
132+
| Retail | 114 | 0.912 (104/114) | 0.895 (102/114) |
133+
| Telecom | 114 | 0.605 (69/114) | 0.588 (67/114) |
134+
| Banking knowledge | 97 | 0.206 (20/97) | 0.196 (19/97) |
135+
| **Total** | **385** | **0.636 (245/385)** | **0.626 (241/385)** |
136136

137137
## Product model
138138

@@ -574,7 +574,10 @@ source/deployment surfaces. See the [VitePress package reference](https://codeso
574574

575575
## Documentation
576576

577-
- [Bilingual VitePress guide and complete package reference](https://codesoul-co.github.io/Hypha/)
577+
- [Bilingual VitePress guide](https://codesoul-co.github.io/Hypha/)
578+
- [Feature-by-feature map](https://codesoul-co.github.io/Hypha/guide/capability-map)
579+
- [Complete module/class/function API](https://codesoul-co.github.io/Hypha/api/)
580+
- [Seven isolated feature examples and full-system example](https://codesoul-co.github.io/Hypha/guide/examples)
578581
- [Official website](https://hypha.code-soul.com/)
579582
- [Documentation index](docs/README.md)
580583
- [Architecture](docs/reference/architecture.md)

‎README.zh-CN.md‎

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -119,14 +119,14 @@ Invalidation 与 Bypass 都属于 Runtime 控制，而不是隐藏的实现细
119119
最新三方对比基于 Hypha `main@ef33263`，每个任务运行一次，共 385 个任务。Base model 为
120120
`deepseek-v4-flash`。Hypha 列为框架结果，Direct 列为直接模型调用基线；两组均未报告系统错误。
121121

122-
| Benchmark | 任务数 | Hypha | Direct |
123-
| --------- | ----: | ----: | ------: |
124-
| Mock | 10 | 0.800（8/10） | 0.800（8/10） |
125-
| Airline | 50 | 0.880（44/50） | 0.900（45/50） |
126-
| Retail | 114 | 0.912（104/114） | 0.895（102/114） |
127-
| Telecom | 114 | 0.605（69/114） | 0.588（67/114） |
128-
| Banking knowledge | 97 | 0.206（20/97） | 0.196（19/97） |
129-
| **合计** | **385** | **0.636（245/385）** | **0.626（241/385）** |
122+
| Benchmark | 任务数 | Hypha | Direct |
123+
| ----------------- | ------: | -------------------: | -------------------: |
124+
| Mock | 10 | 0.800（8/10） | 0.800（8/10） |
125+
| Airline | 50 | 0.880（44/50） | 0.900（45/50） |
126+
| Retail | 114 | 0.912（104/114） | 0.895（102/114） |
127+
| Telecom | 114 | 0.605（69/114） | 0.588（67/114） |
128+
| Banking knowledge | 97 | 0.206（20/97） | 0.196（19/97） |
129+
| **合计** | **385** | **0.636（245/385）** | **0.626（241/385）** |
130130

131131
## 产品模型
132132

@@ -549,7 +549,10 @@ Hypha v1.0.1 已发布 15 个版本对齐的 npm Library；应用应在整个依
549549

550550
## 文档
551551

552-
- [中英双语 VitePress 文档与完整 Package 参考](https://codesoul-co.github.io/Hypha/zh/)
552+
- [中英双语 VitePress 文档](https://codesoul-co.github.io/Hypha/zh/)
553+
- [逐功能地图](https://codesoul-co.github.io/Hypha/zh/guide/capability-map)
554+
- [逐模块/类/函数完整 API](https://codesoul-co.github.io/Hypha/zh/api/)
555+
- [7 个独立功能示例与完整系统示例](https://codesoul-co.github.io/Hypha/zh/guide/examples)
553556
- [官方网站](https://hypha.code-soul.com/)
554557
- [文档索引](docs/README.md)
555558
- [系统架构](docs/reference/architecture.md)

‎docs/README.md‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,16 @@
22

33
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.
44

5-
The published v1.0.0 user guide, all-package atlas, FSM walkthrough, and full-system example are
6-
available at [codesoul-co.github.io/Hypha](https://codesoul-co.github.io/Hypha/). The project website
7-
is [hypha.code-soul.com](https://hypha.code-soul.com/).
5+
The published v1.0.1 user guide, feature map, complete generated API reference, FSM walkthrough, and
6+
full-system example are available at
7+
[codesoul-co.github.io/Hypha](https://codesoul-co.github.io/Hypha/). The project website is
8+
[hypha.code-soul.com](https://hypha.code-soul.com/).
89

910
## Start Here
1011

12+
- [Feature Map](https://codesoul-co.github.io/Hypha/guide/capability-map): end-to-end execution stages mapped to packages, modules, principal classes/functions, and isolated examples.
13+
- [Complete API Reference](https://codesoul-co.github.io/Hypha/api/): every public package export grouped by source module, including signatures and public class/interface members.
14+
- [Runnable Examples](https://codesoul-co.github.io/Hypha/guide/examples): seven isolated feature entries, a 15-package tour, DomainPack compilation, Server Run submission, and custom FSM control.
1115
- [Architecture Reference](reference/architecture.md): package responsibilities, harness semantics, runtime boundaries, and extension rules.
1216
- [Runtime Model](reference/runtime-model.md): DomainPack, Session, Run, Event, durable orchestration, FSM, replay, audit, regression, and concurrency conventions.
1317
- [FSM Anomaly Recovery](architecture/fsm-recovery.md): cross-module supervision, evidence-based convergence, bounded recovery states, cache knowledge, and module failure matrix.

‎examples/release-agent/README.md‎

Lines changed: 52 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -6,17 +6,19 @@ it does not edit framework source.
66

77
## Parts
88

9-
| File | Product responsibility |
10-
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
11-
| `agent/domain-pack.yaml` | Task/input, output contract, workflow, Tool/Skill allow-lists, Memory/reasoning profiles, policy, evaluation, regression, and deployment. |
12-
| `agent/prompt.json` | Versioned Agent Prompt registered through the Runtime API. |
13-
| `agent/skill.md` | Progressively loaded Skill instructions and declared trust metadata. |
14-
| `agent/hypha.user.yaml` | Product-owned Server configuration overlay. |
15-
| `src/agent.ts` | Loads and validates the DomainPack, compiles its custom workflow FSM, and applies the Agent patch. |
16-
| `src/package-tour.ts` | Imports all 15 public packages and exercises one representative contract or runtime boundary from each. |
17-
| `src/contract.test.ts` | Proves deterministic compilation, Harness system output, output contract, and selected capabilities. |
18-
| `src/run-agent.ts` | Registers Prompt/Skill and submits a durable Session start-run command over HTTP. |
19-
| `src/run-fsm.ts` | Starts the compiled custom FSM, inspects its revision, and applies one governed owner transition. |
9+
| File | Product responsibility |
10+
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
11+
| `agent/domain-pack.yaml` | Task/input, output contract, workflow, Tool/Skill allow-lists, Memory/reasoning profiles, policy, evaluation, regression, and deployment. |
12+
| `agent/prompt.json` | Versioned Agent Prompt registered through the Runtime API. |
13+
| `agent/skill.md` | Progressively loaded Skill instructions and declared trust metadata. |
14+
| `agent/hypha.user.yaml` | Product-owned Server configuration overlay. |
15+
| `src/agent.ts` | Loads and validates the DomainPack, compiles its custom workflow FSM, and applies the Agent patch. |
16+
| `src/features/*.ts` | Seven isolated examples covering contracts/storage, FSM, inference/models, capabilities, composition, Events/Harness/adapters, and cache/testing. |
17+
| `src/run-feature.ts` | Selects and runs one feature example by name. |
18+
| `src/package-tour.ts` | Composes all feature examples and the release Agent into one 15-package smoke run. |
19+
| `src/contract.test.ts` | Proves deterministic compilation and asserts real output from every isolated feature example. |
20+
| `src/run-agent.ts` | Registers Prompt/Skill and submits a durable Session start-run command over HTTP. |
21+
| `src/run-fsm.ts` | Starts the compiled custom FSM, inspects its revision, and applies one governed owner transition. |
2022

2123
The Tool entry is a contract and permission declaration. The concrete `search` adapter is
2224
registered by trusted Server composition; DomainPack YAML does not gain execution authority merely
@@ -52,6 +54,7 @@ release, then install the matching packages:
5254

5355
```bash
5456
npm install
57+
npm run feature -- fsm
5558
npm run tour
5659
npm run compile-agent
5760
npm test
@@ -61,7 +64,44 @@ All `@codesoul-co/hypha-*` dependencies should remain on one release line. v1.0.
6164
published release represented by this example. During Hypha repository development, the root
6265
command `npm run typecheck:release-example` checks the same source against workspace packages.
6366

64-
`npm run tour` prints a JSON inventory only after all 15 representative boundaries succeed.
67+
## Run one feature at a time
68+
69+
The feature runner keeps each example small enough to copy into an application without importing
70+
the full system:
71+
72+
| Command | Source | Packages and behavior |
73+
| -------------------------------------------- | ------------------------------------- | --------------------------------------------------------------------- |
74+
| `npm run feature -- core-storage` | `features/core-storage.ts` | Validate a system spec and create a SQLite storage topology |
75+
| `npm run feature -- fsm` | `features/fsm.ts` | Parse a process, analyze topology and create an initial Snapshot |
76+
| `npm run feature -- inference-models` | `features/inference-models.ts` | Register deterministic providers, route a model and execute inference |
77+
| `npm run feature -- capabilities` | `features/capabilities.ts` | Register a Tool and Skill and validate an MCP allow-list |
78+
| `npm run feature -- domain-kernel-memory` | `features/domain-kernel-memory.ts` | Validate Domain, ReAct Agent and Memory composition contracts |
79+
| `npm run feature -- events-harness-adapters` | `features/events-harness-adapters.ts` | Record an Event, project a Session and create local profiles |
80+
| `npm run feature -- cache-testing` | `features/cache-testing.ts` | Write/read a deterministic cache entry and assert a state path |
81+
82+
For example:
83+
84+
```bash
85+
npm run feature -- fsm
86+
```
87+
88+
```json
89+
{
90+
"feature": "fsm",
91+
"result": {
92+
"processId": "fsm.react.default",
93+
"initialState": "Idle",
94+
"reachableStates": ["Idle", "Reasoning", "HumanReview", "Completed", "Failed"],
95+
"unreachableStates": [],
96+
"terminalStates": ["Completed", "Failed"]
97+
}
98+
}
99+
```
100+
101+
`npm run tour` runs all seven entries and prints a JSON inventory only after all 15 representative
102+
package boundaries succeed. `npm test` asserts the important values instead of only checking that
103+
the imports execute.
104+
65105
`npm run compile-agent` then prints two intentionally separate processes:
66106

67107
- `reactHarnessFsm` is framework-owned and protects ReAct lifecycle, policy, effects, verification,

‎examples/release-agent/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
"scripts": {
77
"build": "tsc -p tsconfig.json",
88
"compile-agent": "npm run build && node dist/compile-agent.js",
9+
"feature": "npm run build && node dist/run-feature.js",
910
"tour": "npm run build && node dist/package-tour.js",
1011
"test": "npm run build && node dist/contract.test.js",
1112
"run": "npm run build && node dist/run-agent.js",

‎examples/release-agent/src/contract.test.ts‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import assert from 'node:assert/strict';
22
import { buildReleaseAgent } from './agent';
3+
import { runAllFeatureExamples } from './features';
34

45
async function main(): Promise<void> {
56
const first = await buildReleaseAgent();
@@ -25,6 +26,16 @@ async function main(): Promise<void> {
2526
assert.deepEqual(first.agent.toolRefs, ['search']);
2627
assert.deepEqual(first.agent.skillRefs, [{ id: 'skill.release-research', version: '1.0.0' }]);
2728

29+
const features = await runAllFeatureExamples();
30+
assert.equal(features['core-storage'].storageEngines[0], 'sqlite');
31+
assert.equal(features.fsm.initialState, 'Idle');
32+
assert.equal(features['inference-models'].inferenceOutput, 'provider-neutral inference');
33+
assert.equal(features.capabilities.toolId, 'tool.search');
34+
assert.equal(features['domain-kernel-memory'].memoryProfileId, 'memory.default');
35+
assert.deepEqual(features['events-harness-adapters'].sessionIds, ['session-tour']);
36+
assert.equal(features['cache-testing'].cacheHit, true);
37+
assert.equal(features['cache-testing'].statePathMatches, true);
38+
2839
process.stdout.write('Release Agent contract is deterministic and valid.\n');
2940
}
3041

‎examples/release-agent/src/features/cache-testing.ts‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
import { createFrameworkEvent } from '@codesoul-co/hypha-core';
2+
import { MemoryCacheStore, ServingCacheManager } from '@codesoul-co/hypha-serving-cache';
3+
import { assertStatePath } from '@codesoul-co/hypha-testing';
4+
5+
/** Exercise deterministic cache keys and a replay-style state-path assertion. */
6+
export async function runCacheTestingExample() {
7+
const cache = new ServingCacheManager({ store: new MemoryCacheStore() });
8+
const key = cache.keyFor({
9+
provider: 'mock-tour',
10+
model: 'mock',
11+
messages: [{ role: 'user', content: 'cache this' }],
12+
});
13+
await cache.set(
14+
key,
15+
{ content: 'cached result' },
16+
{ provider: 'mock-tour', model: 'mock', cacheType: 'exact' }
17+
);
18+
19+
const event = createFrameworkEvent({
20+
id: 'event-fixture-1',
21+
type: 'run.created',
22+
userId: 'owner',
23+
sessionId: 'session-fixture',
24+
runId: 'run-fixture',
25+
payload: {},
26+
});
27+
const statePathMatches = assertStatePath(
28+
{ id: 'fixture-tour', version: '1.0.0', events: [event], statePath: ['Created'] },
29+
['Created']
30+
);
31+
32+
return {
33+
cacheHit: Boolean(await cache.get(key)),
34+
statePathMatches,
35+
};
36+
}

‎examples/release-agent/src/features/capabilities.ts‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
import { mcpIntegrationSpecDefinition } from '@codesoul-co/hypha-mcp';
2+
import { SkillRegistry, skillSpecDefinition } from '@codesoul-co/hypha-skills';
3+
import { ToolRegistry, toolSpecDefinition } from '@codesoul-co/hypha-tools';
4+
5+
/** Register Skills and Tools, and validate the MCP allow-list boundary. */
6+
export function runCapabilitiesExample() {
7+
const tool = toolSpecDefinition.parse(toolSpecDefinition.example);
8+
const tools = new ToolRegistry();
9+
tools.register(tool, async (input) => ({ input, source: 'feature-example' }));
10+
11+
const skill = skillSpecDefinition.parse(skillSpecDefinition.example);
12+
const skills = new SkillRegistry();
13+
skills.register(skill);
14+
15+
const mcp = mcpIntegrationSpecDefinition.parse(mcpIntegrationSpecDefinition.example);
16+
17+
return {
18+
toolId: tools.getSpec(tool.id)?.id,
19+
skillIds: skills.list().map((entry) => entry.id),
20+
mcpServerIds: mcp.servers.map((server) => server.id),
21+
};
22+
}

‎examples/release-agent/src/features/core-storage.ts‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
import { harnessedAgentSystemSpecDefinition } from '@codesoul-co/hypha-core';
2+
import {
3+
createSQLiteStorageProfile,
4+
storageTopologySpecDefinition,
5+
} from '@codesoul-co/hypha-storage';
6+
7+
/** Validate the shared system contract and compose a local storage topology. */
8+
export function runCoreStorageExample() {
9+
const system = harnessedAgentSystemSpecDefinition.parse(
10+
harnessedAgentSystemSpecDefinition.example
11+
);
12+
const sqlite = createSQLiteStorageProfile({
13+
id: 'storage.example',
14+
role: 'source_of_truth',
15+
uri: 'file:./var/example.sqlite',
16+
database: './var/example.sqlite',
17+
});
18+
const topology = storageTopologySpecDefinition.parse({
19+
...storageTopologySpecDefinition.example,
20+
providers: [sqlite],
21+
});
22+
23+
return {
24+
systemId: system.id,
25+
storageEngines: topology.providers.map((provider) => provider.engine),
26+
};
27+
}

‎examples/release-agent/src/features/domain-kernel-memory.ts‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
import { domainPackSpecDefinition } from '@codesoul-co/hypha-domain';
2+
import { reactAgentSpecDefinition } from '@codesoul-co/hypha-kernel';
3+
import { memorySpecDefinition } from '@codesoul-co/hypha-memory';
4+
5+
/** Validate composition contracts without embedding domain behavior in Core. */
6+
export function runDomainKernelMemoryExample() {
7+
const domain = domainPackSpecDefinition.parse(domainPackSpecDefinition.example);
8+
const agent = reactAgentSpecDefinition.parse(reactAgentSpecDefinition.example);
9+
const memory = memorySpecDefinition.parse(memorySpecDefinition.example);
10+
11+
return {
12+
domainPackId: domain.id,
13+
agentId: agent.id,
14+
memoryProfileId: memory.id,
15+
};
16+
}

0 commit comments

Comments
 (0)