@ddse/acm-sdk 0.5.0 → 0.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +50 -1
- package/dist/src/context.d.ts +3 -0
- package/dist/src/context.d.ts.map +1 -1
- package/dist/src/context.js +4 -1
- package/dist/src/context.js.map +1 -1
- package/dist/src/nucleus.d.ts +35 -0
- package/dist/src/nucleus.d.ts.map +1 -1
- package/dist/src/nucleus.js +350 -25
- package/dist/src/nucleus.js.map +1 -1
- package/dist/src/types.d.ts +2 -0
- package/dist/src/types.d.ts.map +1 -1
- package/dist/tests/phase4-integration.test.js +5 -2
- package/dist/tests/phase4-integration.test.js.map +1 -1
- package/dist/tests/query-context.test.d.ts +2 -0
- package/dist/tests/query-context.test.d.ts.map +1 -0
- package/dist/tests/query-context.test.js +1239 -0
- package/dist/tests/query-context.test.js.map +1 -0
- package/dist/tsconfig.tsbuildinfo +1 -1
- package/package.json +16 -2
- package/src/capability.ts +0 -11
- package/src/context-provider.ts +0 -136
- package/src/context.ts +0 -190
- package/src/index.ts +0 -12
- package/src/nucleus.ts +0 -341
- package/src/policy.ts +0 -9
- package/src/registry.ts +0 -7
- package/src/stream.ts +0 -24
- package/src/task.ts +0 -38
- package/src/tool.ts +0 -6
- package/src/types.ts +0 -233
- package/src/utils.ts +0 -271
- package/tests/phase4-integration.test.ts +0 -138
- package/tsconfig.json +0 -8
- package/tsconfig.tsbuildinfo +0 -1
package/README.md
CHANGED
|
@@ -20,6 +20,8 @@ pnpm add @ddse/acm-sdk
|
|
|
20
20
|
- **Task<I, O>**: Base class for logical task units
|
|
21
21
|
- **CapabilityRegistry**: Interface for task registries
|
|
22
22
|
- **ToolRegistry**: Interface for tool registries
|
|
23
|
+
- **Nucleus**: Abstract reasoning core with preflight, invoke, and postcheck lifecycle
|
|
24
|
+
- **DeterministicNucleus**: Concrete nucleus with built-in context tools, token budget enforcement, and anti-hallucination grounding
|
|
23
25
|
|
|
24
26
|
### Types
|
|
25
27
|
|
|
@@ -30,11 +32,17 @@ pnpm add @ddse/acm-sdk
|
|
|
30
32
|
- **LedgerEntry**: Memory ledger entry
|
|
31
33
|
- **PolicyDecision**: Authorization result
|
|
32
34
|
- **RunContext**: Execution context passed to tasks
|
|
35
|
+
- **NucleusConfig**: Nucleus configuration including `maxContextTokens`, `maxQueryRounds`, and `contextProvider`
|
|
36
|
+
- **NucleusInvokeResult**: Invoke result with optional `metrics` (rounds, estimatedPromptTokens, budgetExhausted)
|
|
33
37
|
|
|
34
38
|
### Utilities
|
|
35
39
|
|
|
36
40
|
- **DefaultStreamSink**: Stream multiplexer for real-time updates
|
|
37
41
|
- **PolicyEngine**: Interface for policy decision points
|
|
42
|
+
- **ContextBuilder**: Fluent builder for constructing Context objects with content-addressable refs
|
|
43
|
+
- **InternalContextScopeImpl**: Runtime artifact scope with `sizeBytes` tracking and wide provenance support
|
|
44
|
+
- **ExternalContextProviderAdapter**: Bridges Nucleus retrieval directives to developer-supplied tools
|
|
45
|
+
- **estimateTokens(text)**: Heuristic token estimator with code-aware char/token ratios (aligned with production BudgetManager)
|
|
38
46
|
|
|
39
47
|
## Usage
|
|
40
48
|
|
|
@@ -215,7 +223,48 @@ This package implements the core abstractions from ACM v0.5:
|
|
|
215
223
|
- **Tool**: Section 2.5
|
|
216
224
|
- **Context**: Section 4
|
|
217
225
|
- **Plan**: Section 5.4
|
|
226
|
+
- **Nucleus**: Reasoning core with context tools and token budget
|
|
227
|
+
|
|
228
|
+
## Nucleus Features
|
|
229
|
+
|
|
230
|
+
### Built-in Context Tools
|
|
231
|
+
|
|
232
|
+
The `DeterministicNucleus` auto-injects two tools into every LLM call:
|
|
233
|
+
|
|
234
|
+
1. **`query_context`** — Read data already in scope (`list`, `read_fact`, `read_augmentation`, `read_assumptions`, `read_artifact`).
|
|
235
|
+
2. **`request_context_retrieval`** — Fetch external data not in scope; fulfilled inline when a `contextProvider` is configured.
|
|
236
|
+
|
|
237
|
+
### Token Budget Enforcement
|
|
238
|
+
|
|
239
|
+
Set `maxContextTokens` on `NucleusConfig` to pass the model's context window size. The `callLLM` loop estimates cumulative prompt tokens using `estimateTokens()` and forces a final answer (stripping built-in tools) when usage exceeds 85% of the budget.
|
|
240
|
+
|
|
241
|
+
```typescript
|
|
242
|
+
const config: NucleusConfig = {
|
|
243
|
+
goalId: 'g1',
|
|
244
|
+
goalIntent: 'Analyze the codebase',
|
|
245
|
+
contextRef: 'sha256-abc',
|
|
246
|
+
llmCall: { provider: 'vllm', model: 'Qwen/Qwen3-4B', maxTokens: 4096 },
|
|
247
|
+
maxContextTokens: 20480, // model's context window
|
|
248
|
+
maxQueryRounds: 25, // max tool loop iterations (default 25)
|
|
249
|
+
};
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
The result includes metrics:
|
|
253
|
+
|
|
254
|
+
```typescript
|
|
255
|
+
const result = await nucleus.invoke({ input: task, tools: myTools });
|
|
256
|
+
console.log(result.metrics);
|
|
257
|
+
// { rounds: 3, estimatedPromptTokens: 12400, budgetExhausted: false }
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
### Anti-Hallucination Grounding
|
|
261
|
+
|
|
262
|
+
All prompts include grounding directives that force the LLM to:
|
|
263
|
+
- Use `query_context` before generating output
|
|
264
|
+
- Cite which fact keys, augmentation indices, or artifact IDs were read
|
|
265
|
+
- Refuse to fabricate information not present in context
|
|
266
|
+
- Call `request_context_retrieval` when needed data is missing
|
|
218
267
|
|
|
219
268
|
## License
|
|
220
269
|
|
|
221
|
-
|
|
270
|
+
MIT
|
package/dist/src/context.d.ts
CHANGED
|
@@ -22,10 +22,12 @@ export declare class InternalContextScopeImpl implements InternalContextScope {
|
|
|
22
22
|
type: string;
|
|
23
23
|
content: any;
|
|
24
24
|
digest: string;
|
|
25
|
+
sizeBytes?: number;
|
|
25
26
|
provenance?: {
|
|
26
27
|
retrievedAt: number;
|
|
27
28
|
tool?: string;
|
|
28
29
|
rationale?: string;
|
|
30
|
+
[key: string]: any;
|
|
29
31
|
};
|
|
30
32
|
}>;
|
|
31
33
|
private ledgerAppend?;
|
|
@@ -34,6 +36,7 @@ export declare class InternalContextScopeImpl implements InternalContextScope {
|
|
|
34
36
|
addArtifact(type: string, content: any, provenance?: {
|
|
35
37
|
tool?: string;
|
|
36
38
|
rationale?: string;
|
|
39
|
+
[extra: string]: any;
|
|
37
40
|
}): string;
|
|
38
41
|
promote(artifactId: string): Promise<void>;
|
|
39
42
|
getArtifact(id: string): any;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/context.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEnF,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAgC;IAC/C,OAAO,CAAC,KAAK,CAA2B;IACxC,OAAO,CAAC,WAAW,CAAgB;IACnC,OAAO,CAAC,aAAa,CAAsC;IAC3D,OAAO,CAAC,UAAU,CAAmC;IAErD,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,IAAI;IAM1D,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI;IAKtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAK1C,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAKvC,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAKrD,aAAa,CAAC,UAAU,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,IAAI;IAK5D,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,aAAa;IActC,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,aAAa;IAMrB,MAAM,CAAC,iBAAiB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM;CAYzD;AAED,qBAAa,wBAAyB,YAAW,oBAAoB;IACnE,SAAS,EAAE,KAAK,CAAC;QACf,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,GAAG,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,CAAC,EAAE;YACX,WAAW,EAAE,MAAM,CAAC;YACpB,IAAI,CAAC,EAAE,MAAM,CAAC;YACd,SAAS,CAAC,EAAE,MAAM,CAAC;SACpB,CAAC;KACH,CAAC,CAAM;IAER,OAAO,CAAC,YAAY,CAAC,CAA+B;IACpD,OAAO,CAAC,cAAc,CAAC,CAAiB;gBAE5B,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI;IAIvD,WAAW,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,GAAG,EACZ,UAAU,CAAC,EAAE;QACX,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;
|
|
1
|
+
{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/context.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEnF,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAgC;IAC/C,OAAO,CAAC,KAAK,CAA2B;IACxC,OAAO,CAAC,WAAW,CAAgB;IACnC,OAAO,CAAC,aAAa,CAAsC;IAC3D,OAAO,CAAC,UAAU,CAAmC;IAErD,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,IAAI;IAM1D,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI;IAKtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAK1C,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAKvC,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAKrD,aAAa,CAAC,UAAU,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,IAAI;IAK5D,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,aAAa;IActC,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,aAAa;IAMrB,MAAM,CAAC,iBAAiB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM;CAYzD;AAED,qBAAa,wBAAyB,YAAW,oBAAoB;IACnE,SAAS,EAAE,KAAK,CAAC;QACf,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,GAAG,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE;YACX,WAAW,EAAE,MAAM,CAAC;YACpB,IAAI,CAAC,EAAE,MAAM,CAAC;YACd,SAAS,CAAC,EAAE,MAAM,CAAC;YACnB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;SACpB,CAAC;KACH,CAAC,CAAM;IAER,OAAO,CAAC,YAAY,CAAC,CAA+B;IACpD,OAAO,CAAC,cAAc,CAAC,CAAiB;gBAE5B,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI;IAIvD,WAAW,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,GAAG,EACZ,UAAU,CAAC,EAAE;QACX,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,CAAC;KACtB,GACA,MAAM;IAsCH,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BhD,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,GAAG;IAK5B,OAAO,CAAC,aAAa;CAKtB"}
|
package/dist/src/context.js
CHANGED
|
@@ -82,12 +82,15 @@ export class InternalContextScopeImpl {
|
|
|
82
82
|
}
|
|
83
83
|
addArtifact(type, content, provenance) {
|
|
84
84
|
const id = `artifact-${Date.now()}-${Math.random().toString(36).substring(7)}`;
|
|
85
|
-
const
|
|
85
|
+
const serialized = typeof content === 'string' ? content : JSON.stringify(content);
|
|
86
|
+
const digest = this.computeDigest(serialized);
|
|
87
|
+
const sizeBytes = Buffer.byteLength(serialized, 'utf8');
|
|
86
88
|
this.artifacts.push({
|
|
87
89
|
id,
|
|
88
90
|
type,
|
|
89
91
|
content,
|
|
90
92
|
digest,
|
|
93
|
+
sizeBytes,
|
|
91
94
|
provenance: provenance
|
|
92
95
|
? {
|
|
93
96
|
retrievedAt: Date.now(),
|
package/dist/src/context.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/context.ts"],"names":[],"mappings":"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
|
|
1
|
+
{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/context.ts"],"names":[],"mappings":"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"}
|
package/dist/src/nucleus.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { Context, InternalContextScope, LedgerEntry } from './types.js';
|
|
2
|
+
import type { ExternalContextProviderAdapter } from './context-provider.js';
|
|
2
3
|
export type NucleusToolDefinition = {
|
|
3
4
|
name: string;
|
|
4
5
|
description?: string;
|
|
@@ -27,6 +28,15 @@ export type NucleusInvokeResult = {
|
|
|
27
28
|
reasoning?: string;
|
|
28
29
|
toolCalls: StructuredToolCall[];
|
|
29
30
|
raw?: any;
|
|
31
|
+
/** Token usage metrics from the callLLM loop */
|
|
32
|
+
metrics?: {
|
|
33
|
+
/** Total rounds executed (including query_context/retrieval rounds) */
|
|
34
|
+
rounds: number;
|
|
35
|
+
/** Estimated cumulative prompt tokens across all rounds */
|
|
36
|
+
estimatedPromptTokens: number;
|
|
37
|
+
/** Whether the loop was terminated early due to token budget */
|
|
38
|
+
budgetExhausted: boolean;
|
|
39
|
+
};
|
|
30
40
|
};
|
|
31
41
|
export type NucleusConfig = {
|
|
32
42
|
goalId: string;
|
|
@@ -49,6 +59,17 @@ export type NucleusConfig = {
|
|
|
49
59
|
};
|
|
50
60
|
promptTemplate?: string;
|
|
51
61
|
promptDigest?: string;
|
|
62
|
+
/** Max query_context rounds the LLM may use before forced to answer. Default 25. */
|
|
63
|
+
maxQueryRounds?: number;
|
|
64
|
+
/** External context provider for mid-invoke retrieval. When set, request_context_retrieval calls are fulfilled inline. */
|
|
65
|
+
contextProvider?: ExternalContextProviderAdapter;
|
|
66
|
+
/**
|
|
67
|
+
* Maximum context window tokens the underlying model supports.
|
|
68
|
+
* When set, the callLLM loop estimates cumulative prompt tokens per round
|
|
69
|
+
* and forces a final answer when usage exceeds 85% of this budget.
|
|
70
|
+
* Passed from infrastructure (e.g. LlmConfig.maxContext via BudgetManager).
|
|
71
|
+
*/
|
|
72
|
+
maxContextTokens?: number;
|
|
52
73
|
};
|
|
53
74
|
export type PreflightResult = {
|
|
54
75
|
status: 'OK';
|
|
@@ -70,6 +91,12 @@ export type LLMCallFn = (prompt: string, tools: NucleusToolDefinition[], config:
|
|
|
70
91
|
toolCalls: StructuredToolCall[];
|
|
71
92
|
raw?: any;
|
|
72
93
|
}>;
|
|
94
|
+
/**
|
|
95
|
+
* Estimate token count from a text string using char/token ratio heuristics.
|
|
96
|
+
* Aligned with BudgetManager.estimateTokens from aiagent infrastructure.
|
|
97
|
+
* Code and structured text use lower ratios (higher token density).
|
|
98
|
+
*/
|
|
99
|
+
export declare function estimateTokens(text: string | undefined | null): number;
|
|
73
100
|
export declare abstract class Nucleus {
|
|
74
101
|
protected config: NucleusConfig;
|
|
75
102
|
constructor(config: NucleusConfig);
|
|
@@ -94,6 +121,14 @@ export declare class DeterministicNucleus extends Nucleus {
|
|
|
94
121
|
getInternalContext(): InternalContextScope | undefined;
|
|
95
122
|
setInternalContext(scope: InternalContextScope): void;
|
|
96
123
|
private callLLM;
|
|
124
|
+
/**
|
|
125
|
+
* Resolve an array of query_context tool calls, returning formatted result strings.
|
|
126
|
+
*/
|
|
127
|
+
private resolveQueryCalls;
|
|
128
|
+
/**
|
|
129
|
+
* Execute a query_context tool call against this.config.context and this.internalContext
|
|
130
|
+
*/
|
|
131
|
+
private executeQueryContext;
|
|
97
132
|
private buildPreflightPrompt;
|
|
98
133
|
private buildInvokePrompt;
|
|
99
134
|
private buildPostcheckPrompt;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"nucleus.d.ts","sourceRoot":"","sources":["../../src/nucleus.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAoB,MAAM,YAAY,CAAC;
|
|
1
|
+
{"version":3,"file":"nucleus.d.ts","sourceRoot":"","sources":["../../src/nucleus.ts"],"names":[],"mappings":"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"}
|