pi-revit 0.3.1 → 0.5.0

package/extensions/pi-revit/contracts.ts

@@ -0,0 +1,146 @@
+import { createHash } from "node:crypto";
+import snapshot from "../../skills/pi-revit/contracts.generated.json";
+
+/**
+ * Resource contract v2. Bridge tools declare it in C# (ITool.Keywords/Limits/Verification);
+ * Pi-native tools declare it here. scripts/generate-contracts.mjs snapshots both into
+ * skills/pi-revit/contracts.generated.json for offline discovery and manual generation.
+ * Code is the single owner; the snapshot is generated and checked, never hand-edited.
+ */
+export type AlternativeKind = "tool" | "api" | "user" | "revit_unsupported";
+export type VerificationKind = "reread" | "capture" | "inspect_output" | "none";
+export interface ToolLimit { what: string; alternative: { kind: AlternativeKind; ref: string | null } }
+export interface ToolContract {
+	name: string;
+	source: "bridge" | "native";
+	tier: string | null;
+	write: boolean;
+	effects: string[];
+	requires_document: boolean;
+	/** Document kinds a bridge tool works in ("project", "family"); null for native utilities. */
+	document_kinds: string[] | null;
+	keywords: string[];
+	limits: ToolLimit[];
+	verification: VerificationKind | null;
+	contract_hash: string;
+	parameters: unknown;
+}
+export const ALTERNATIVE_KINDS: readonly AlternativeKind[] = ["tool", "api", "user", "revit_unsupported"];
+export const VERIFICATION_KINDS: readonly VerificationKind[] = ["reread", "capture", "inspect_output", "none"];
+
+const limit = (what: string, kind: AlternativeKind, ref: string): ToolLimit => ({ what, alternative: { kind, ref } });
+
+/** Contracts of tools implemented by this extension (not advertised by a bridge). */
+export const NATIVE_CONTRACTS: Record<string, Pick<ToolContract, "keywords" | "limits" | "verification" | "effects" | "write">> = {
+	ping: {
+		keywords: ["connection", "status", "version", "revit running", "bridge", "loaded version"],
+		limits: [limit("Whether a project document is open", "tool", "get_model_overview")],
+		verification: null, effects: [], write: false,
+	},
+	manage_revit_instances: {
+		keywords: ["instances", "sessions", "multiple revit", "switch revit", "select session"],
+		limits: [limit("Activating a document inside a Revit session", "user", "Open or activate the document in Revit")],
+		verification: "reread", effects: ["session"], write: false,
+	},
+	find_revit_tools: {
+		keywords: ["capabilities", "what can you do", "tools", "manuals", "documentation", "help", "workflows"],
+		limits: [limit("Reading manual contents", "tool", "read (open the returned path)")],
+		verification: "none", effects: ["session"], write: false,
+	},
+	read_revit_result: {
+		keywords: ["large result", "saved result", "continue result", "next fragment"],
+		limits: [limit("Paging the original query", "tool", "the original query tool (for example get_elements) with its next_offset")],
+		verification: null, effects: [], write: false,
+	},
+	get_revit_operation: {
+		keywords: ["receipt", "timeout", "operation status", "did it run", "retry"],
+		limits: [limit("Operations from an earlier bridge session", "user", "Inspect the model state directly; receipts do not survive a restart")],
+		verification: null, effects: [], write: false,
+	},
+	manage_revit_scripts: {
+		keywords: ["saved scripts", "script library", "reusable script", "run script", "script history"],
+		limits: [limit("Preview or rollback of a script run", "tool", "dedicated tools with preview (set_parameters, transform_elements, delete_elements, manage_views, ...)")],
+		verification: "reread", effects: ["model", "ui", "files", "external"], write: true,
+	},
+};
+
+/** Deterministic JSON with sorted object keys; arrays keep their order. */
+export function canonicalJson(value: unknown): string {
+	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+	if (value !== null && typeof value === "object")
+		return `{${Object.keys(value as object).sort().filter(key => (value as Record<string, unknown>)[key] !== undefined)
+			.map(key => `${JSON.stringify(key)}:${canonicalJson((value as Record<string, unknown>)[key])}`).join(",")}}`;
+	return JSON.stringify(value ?? null);
+}
+
+/**
+ * Executable-contract hash: the input schema and declared effects only. Descriptions,
+ * guidelines, keywords and limits are guidance, so rewording them never flags a bridge
+ * as incompatible. Runtime discovery and the generator share this one function.
+ */
+export function contractHash(descriptor: { parameters?: unknown; write?: boolean; effects?: string[]; requiresDocument?: boolean; documentKinds?: string[] | null }): string {
+	const write = descriptor.write === true;
+	// Support for both document kinds is the default and leaves the hash unchanged; a restriction
+	// is executable behavior, so a project-only tool differs from a bridge that does not declare it.
+	const kinds = [...(descriptor.documentKinds ?? [])].sort();
+	const restricted = kinds.length > 0 && kinds.join(",") !== "family,project";
+	const payload = canonicalJson({
+		parameters: withoutGuidance(descriptor.parameters ?? { type: "object", properties: {} }),
+		write,
+		effects: descriptor.effects ?? (write ? ["model"] : []),
+		requiresDocument: descriptor.requiresDocument ?? true,
+		...(restricted ? { documentKinds: kinds } : {}),
+	});
+	return createHash("sha256").update(payload).digest("hex").slice(0, 16);
+}
+
+/**
+ * Schema annotations are guidance: rewording a property description, title or example
+ * must not flag a bridge as incompatible. Types, required lists, enums, constants,
+ * bounds and defaults remain part of the executable contract. Property names are kept
+ * even when a property is literally called "description".
+ */
+function withoutGuidance(schema: unknown, isPropertyMap = false): unknown {
+	if (Array.isArray(schema)) return schema.map(item => withoutGuidance(item));
+	if (schema === null || typeof schema !== "object") return schema;
+	const result: Record<string, unknown> = {};
+	for (const [key, value] of Object.entries(schema as Record<string, unknown>)) {
+		if (!isPropertyMap && (key === "description" || key === "title" || key === "examples")) continue;
+		result[key] = withoutGuidance(value, !isPropertyMap && (key === "properties" || key === "patternProperties" || key === "$defs" || key === "definitions"));
+	}
+	return result;
+}
+
+export const packagedContracts = new Map((snapshot.tools as ToolContract[]).map(tool => [tool.name, tool]));
+
+/**
+ * The one-call API lookup for an "api" limit: the API names in its reference joined with "; ",
+ * the multi-member form of search_api_docs, so an alternative's members are verified in one call
+ * instead of one search per member. Dotted members and multi-word CamelCase types count; prose
+ * words do not. Null when the reference names no API member. The documentation gate checks every
+ * name against the installed RevitAPI.xml.
+ */
+export function apiLookupQuery(ref: string | null | undefined): string | null {
+	if (!ref) return null;
+	const names = [...ref.matchAll(/\b[A-Z][A-Za-z0-9]*(?:\.[A-Z_][A-Za-z0-9_]*)+\b|\b[A-Z][a-z0-9]+(?:[A-Z][A-Za-z0-9]*)+\b/g)].map(match => match[0]);
+	const unique = [...new Set(names)].slice(0, 10);
+	return unique.length ? unique.join("; ") : null;
+}
+
+/** Limits as shown to the agent: an "api" alternative carries its one-call lookup. */
+export function withApiLookups(limits: ToolLimit[]): (ToolLimit & { lookup?: { tool: "search_api_docs"; query: string } })[] {
+	return limits.map(limit => {
+		const query = limit.alternative.kind === "api" ? apiLookupQuery(limit.alternative.ref) : null;
+		return query ? { ...limit, lookup: { tool: "search_api_docs" as const, query } } : limit;
+	});
+}
+
+/** Normalize a live bridge descriptor's optional v2 fields; absent fields stay unknown. */
+export function descriptorLimits(value: unknown): ToolLimit[] | null {
+	if (!Array.isArray(value)) return null;
+	return value.flatMap(item => {
+		const what = (item as ToolLimit)?.what, kind = (item as ToolLimit)?.alternative?.kind;
+		return typeof what === "string" && ALTERNATIVE_KINDS.includes(kind)
+			? [{ what, alternative: { kind, ref: typeof (item as ToolLimit).alternative.ref === "string" ? (item as ToolLimit).alternative.ref : null } }] : [];
+	});
+}

package/extensions/pi-revit/discovery.ts

@@ -0,0 +1,93 @@
+/**
+ * Discovery over every PI-Revit resource kind: tools, workflows, shared references and
+ * subject skills (present and future). Tool vocabulary is English, one canonical language.
+ * There are no per-language rules: the model translates a request written in any language
+ * into English search words, replies in the user's language, and reads localized Revit
+ * names from results. Matching only normalizes the English vocabulary: case, accents,
+ * simple inflection and word forms, with ranked all-word then partial matches.
+ */
+export interface DiscoveryDocument {
+	name: string;
+	/** Strong fields: name, keywords. Medium: summary, declared limits and input names. Weak: description. */
+	keywords?: readonly string[];
+	summary?: string | null;
+	/** Text of declared limits, so a request just outside a tool finds the tool and its alternative. */
+	limits?: readonly string[];
+	/** Input property names, e.g. "level" or "sheet_id": what a tool can be asked about. */
+	inputs?: readonly string[];
+	description?: string | null;
+}
+export interface DiscoveryMatch<T> { item: T; matched: number; score: number; complete: boolean }
+export interface DiscoveryResult<T> { mode: "all" | "partial" | "none"; groups: number; matches: DiscoveryMatch<T>[] }
+
+/** Words that carry no tool meaning in English search phrases. */
+const STOPWORDS = new Set(["the", "and", "for", "with", "all", "this", "that", "these", "those", "please", "can", "could", "you", "are", "was",
+	"how", "what", "which", "does", "from", "into", "each", "every", "some", "any", "get", "give", "tell", "want", "need", "would", "should",
+	"its", "there", "their", "them", "use", "using", "revit", "model", "project", "pi", "via", "about", "then", "than", "also", "one", "two"]);
+
+export function normalizeText(text: string): string {
+	return text.toLowerCase().normalize("NFKD").replace(/[̀-ͯ]/g, "").replace(/c#/g, "csharp");
+}
+
+export function tokenize(text: string): string[] {
+	return normalizeText(text).split(/[^a-z0-9]+/).filter(token => token.length >= 3 || /\d/.test(token));
+}
+
+/** Simple English inflection stripping. */
+export function stem(token: string): string {
+	if (token.length > 4 && token.endsWith("ies")) return token.slice(0, -3) + "y";
+	if (token.length > 4 && /(ches|shes|xes|sses|zes)$/.test(token)) return token.slice(0, -2);
+	if (token.length > 3 && token.endsWith("s") && !token.endsWith("ss") && !token.endsWith("us")) return token.slice(0, -1);
+	return token;
+}
+
+/** Same word, different form: "connected"/"connection", "rotate"/"rotation", "create"/"creating". */
+function hit(variant: string, term: string) {
+	if (variant === term) return true;
+	if (variant.length < 5 || term.length < 5) return false;
+	let common = 0;
+	while (common < variant.length && common < term.length && variant[common] === term[common]) common++;
+	return common === Math.min(variant.length, term.length) || common >= Math.max(5, Math.min(variant.length, term.length) - 3);
+}
+
+const WEIGHTS = { strong: 3, medium: 2, weak: 1 } as const;
+
+export function createDiscoveryIndex() {
+	/** Meaningful query words; numbers are call arguments, not capability words. */
+	function groups(query: string): string[] {
+		return [...new Set(normalizeText(query).split(/[^a-z0-9]+/)
+			.filter(word => word.length >= 3 && !/^\d+$/.test(word) && !STOPWORDS.has(word)).map(stem))];
+	}
+	function terms(document: DiscoveryDocument) {
+		const strong = [...tokenize(document.name.replaceAll("_", " ")), ...(document.keywords ?? []).flatMap(tokenize)].map(stem);
+		const medium = [document.summary ?? "", ...(document.limits ?? []), ...(document.inputs ?? []).map(name => name.replaceAll("_", " "))]
+			.flatMap(tokenize).map(stem);
+		const weak = tokenize(document.description ?? "").map(stem);
+		return [[WEIGHTS.strong, new Set(strong)], [WEIGHTS.medium, new Set(medium)], [WEIGHTS.weak, new Set(weak)]] as const;
+	}
+	function search<T>(items: readonly T[], query: string, toDocument: (item: T) => DiscoveryDocument): DiscoveryResult<T> {
+		const queryGroups = groups(query);
+		if (queryGroups.length === 0) return { mode: "none", groups: 0, matches: [] };
+		const scored = items.map(item => {
+			const fields = terms(toDocument(item));
+			let matched = 0, score = 0, strongHit = false;
+			for (const word of queryGroups) {
+				let best = 0;
+				for (const [weight, set] of fields) {
+					if (weight <= best) continue;
+					for (const term of set) if (hit(word, term)) { best = weight; break; }
+				}
+				if (best > 0) { matched++; score += best; if (best === WEIGHTS.strong) strongHit = true; }
+			}
+			return { item, matched, score, strongHit, complete: matched === queryGroups.length };
+		});
+		// Complete matches first; then partial matches with most words and a hit on a name or keyword.
+		const needed = Math.max(1, Math.floor(queryGroups.length / 2));
+		const ranked = scored.filter(entry => entry.complete || (entry.matched >= needed && entry.strongHit))
+			.sort((a, b) => Number(b.complete) - Number(a.complete) || b.matched - a.matched || b.score - a.score
+				|| toDocument(a.item).name.localeCompare(toDocument(b.item).name));
+		const mode = ranked.some(entry => entry.complete) ? "all" : ranked.length ? "partial" : "none";
+		return { mode, groups: queryGroups.length, matches: ranked.map(({ item, matched, score, complete }) => ({ item, matched, score, complete })) };
+	}
+	return { search, groups };
+}