Projection: project content under a budget

Shorten text first, then reduce entries; source data, projection result, and budget are explicitly separated by the App.

value should be serializable JSON data. The counts and lengths of defineContentProjection are the attempt order the App specifies; project({value,maxChars}) returns {text,truncated}. When the value is already within budget it returns the JSON.stringify result directly; once over the limit it tries render and then fallback in turn. The fallback result is the App's responsibility and must not be treated as Core's final input budget guarantee.

projectContinuousExcerpt performs a binary-search prefix selection over body text that can be truncated continuously; render(0) already over the limit returns undefined, and existing surrogate pairs are preserved. defineTreeProjection traverses synchronously in property/array order and omits nodes beyond maxDepth or where omit returns true; only undefined means omit, while null, false, and 0 are kept.

Progressive examples for the same business case

Prepare compact JSON for the same query result

Beginner · Node.js

TypeScript

import { Projection } from '@jangts/agent-core/kits/projection';
const projection = Projection.defineContentProjection({
  counts: [10, 3, 1], lengths: [200, 80, 20],
  render: value => JSON.stringify(value), fallback: () => '{}',
});
const result = projection.project({ value: { items: [{ title: '配置说明', body: '正文'.repeat(100) }] }, maxChars: 120 });
console.log(result.text, result.truncated);

JavaScript

import { Projection } from '@jangts/agent-core/kits/projection';
const projection = Projection.defineContentProjection({
    counts: [10, 3, 1], lengths: [200, 80, 20],
    render: value => JSON.stringify(value), fallback: () => '{}',
});
const result = projection.project({ value: { items: [{ title: '配置说明', body: '正文'.repeat(100) }] }, maxChars: 120 });
console.log(result.text, result.truncated);

Remove private fields from the same data, then project under budget

Configuration · Node.js

TypeScript

import { Projection } from '@jangts/agent-core/kits/projection';
const tree = Projection.defineTreeProjection({
  maxDepth: 4,
  visitRecord(record) { delete record.privateNote; },
});
const source = { items: [{ title: '配置说明', body: '正文'.repeat(100), privateNote: '不向模型提供' }] };
// 调用者明确选择副本所有权；visitor 不会碰原记录。
const publicData = tree.visit(structuredClone(source), undefined);
const compact = Projection.defineContentProjection({ counts: [10, 3, 1], lengths: [200, 80, 20], render: JSON.stringify, fallback: () => '{}' });
console.log(compact.project({ value: publicData, maxChars: 120 }));

JavaScript

import { Projection } from '@jangts/agent-core/kits/projection';
const tree = Projection.defineTreeProjection({
    maxDepth: 4,
    visitRecord(record) { delete record.privateNote; },
});
const source = { items: [{ title: '配置说明', body: '正文'.repeat(100), privateNote: '不向模型提供' }] };
// 调用者明确选择副本所有权；visitor 不会碰原记录。
const publicData = tree.visit(structuredClone(source), undefined);
const compact = Projection.defineContentProjection({ counts: [10, 3, 1], lengths: [200, 80, 20], render: JSON.stringify, fallback: () => '{}' });
console.log(compact.project({ value: publicData, maxChars: 120 }));

Keep continuous body text instead of splitting paragraphs

Extension · Node.js

The output length of render must grow monotonically with the prefix length for the binary search to be meaningful.

TypeScript

import { Projection } from '@jangts/agent-core/kits/projection';
const body = '一段连续的资料正文。'.repeat(100);
const excerpt = Projection.projectContinuousExcerpt(body, 120, length => JSON.stringify({ excerpt: body.slice(0, length) }));
if (excerpt) console.log(JSON.parse(excerpt.text));

JavaScript

import { Projection } from '@jangts/agent-core/kits/projection';
const body = '一段连续的资料正文。'.repeat(100);
const excerpt = Projection.projectContinuousExcerpt(body, 120, length => JSON.stringify({ excerpt: body.slice(0, length) }));
if (excerpt)
    console.log(JSON.parse(excerpt.text));

Policies & implementations

• Reduction order and tree traversal