@thomasfosterau/effect-rdf 0.0.0-stage → 0.1.0

package/dist/Tools-ryxphZbI.mjs

@@ -0,0 +1,329 @@
+import { t as __exportAll } from "./rolldown-runtime-D8jQpDG7.mjs";
+import { B as isNamedNode, Q as quad, Y as literal, Z as namedNode, z as isLiteral } from "./Term-CFLG1qu4.mjs";
+import { n as IriSchema } from "./Iri-Cr92gsQV.mjs";
+import { c as serialize } from "./Turtle-CZVUOtwl.mjs";
+import { y as transform } from "./Algebra-CGG4oae3.mjs";
+import { _ as toRecord, c as getUndefined } from "./Bindings-Ck3m7JRC.mjs";
+import { n as SparqlEngine } from "./Engine-DF8PN7g-.mjs";
+import { i as parseQuery } from "./Parser-xARsOWXk.mjs";
+import { a as translateQuery } from "./Translate-gzWPq0Ia.mjs";
+import { _ as termToJson, r as JsonResultsSchema } from "./Results-peJjGA2V.mjs";
+import * as Schema from "effect/Schema";
+import * as Effect from "effect/Effect";
+import * as Match from "effect/Match";
+import * as Record from "effect/Record";
+import * as Stream from "effect/Stream";
+import * as Duration from "effect/Duration";
+import { Tool, Toolkit } from "effect/ai";
+// src/sparql/ai/Tools.ts
+/**
+* Knowledge-graph tools for `effect/ai`: a `Toolkit` of SPARQL and dataset
+* tools over the `SparqlEngine` service, for `LanguageModel.generateText`
+* and for MCP (see `Mcp`).
+*
+* | Tool                | What it does                                                          |
+* | ------------------- | --------------------------------------------------------------------- |
+* | `sparql_query`      | Runs a read-only SELECT / ASK / CONSTRUCT / DESCRIBE query            |
+* | `describe_resource` | The triples whose subject is an IRI (one hop)                         |
+* | `list_classes`      | Classes in use or declared (`rdfs:Class`, `owl:Class`), with counts   |
+* | `list_properties`   | Predicates in use or declared, with counts                            |
+* | `search_labels`     | IRIs whose `rdfs:label` / `skos:prefLabel` contains a string          |
+* | `sparql_update`     | Runs a SPARQL Update — only in `toolkitWithUpdate`, off by default    |
+*
+* Tool input is model-generated, so it is untrusted: queries are read-only
+* (the query tool only accepts queries; updates need the separate,
+* opt-in tool), every result is capped at `maxRows` rows or triples (and
+* reports whether it was truncated), every call has a `timeout`, and
+* `SERVICE` (federation) is refused unless `federation: true`. Failures are
+* returned to the model as a `SparqlToolError` rather than failing the
+* conversation.
+*
+* @since 0.1.0
+*/
+var Tools_exports = /* @__PURE__ */ __exportAll({
+	DescribeResource: () => DescribeResource,
+	ListClasses: () => ListClasses,
+	ListProperties: () => ListProperties,
+	SearchLabels: () => SearchLabels,
+	SparqlQuery: () => SparqlQuery,
+	SparqlToolError: () => SparqlToolError,
+	SparqlUpdate: () => SparqlUpdate,
+	handlers: () => handlers,
+	layer: () => layer,
+	layerWithUpdate: () => layerWithUpdate,
+	toolkit: () => toolkit,
+	toolkitWithUpdate: () => toolkitWithUpdate
+});
+/**
+* Why a tool call failed (a syntax error, a refused `SERVICE`, a timeout, …),
+* returned to the model as the tool's result.
+*
+* @since 0.1.0
+* @category errors
+*/
+var SparqlToolError = class extends Schema.TaggedError()("SparqlToolError", { message: Schema.String }) {};
+const Limit = Schema.optional(Schema.Int.check(Schema.isGreaterThan(0)).annotate({ description: "The most rows or triples to return (capped by the server)." }));
+const IriParam = IriSchema.annotate({ description: "An absolute IRI, e.g. http://example.org/alice" });
+/**
+* Runs a read-only SPARQL query. SELECT results are SPARQL JSON results,
+* ASK a boolean, CONSTRUCT / DESCRIBE a Turtle document.
+*
+* @since 0.1.0
+* @category tools
+*/
+const SparqlQuery = Tool.make("sparql_query", {
+	description: "Run a read-only SPARQL 1.1 query (SELECT, ASK, CONSTRUCT or DESCRIBE) against the knowledge graph. SELECT returns SPARQL JSON results, ASK a boolean, CONSTRUCT and DESCRIBE a Turtle document. Results are truncated to a row limit.",
+	parameters: Schema.Struct({
+		query: Schema.String.annotate({ description: "The SPARQL query text, with any PREFIX declarations." }),
+		limit: Limit
+	}),
+	success: Schema.Union([
+		Schema.Struct({
+			type: Schema.Literal("select"),
+			results: JsonResultsSchema,
+			isTruncated: Schema.Boolean
+		}),
+		Schema.Struct({
+			type: Schema.Literal("ask"),
+			isTrue: Schema.Boolean
+		}),
+		Schema.Struct({
+			type: Schema.Literal("graph"),
+			turtle: Schema.String,
+			isTruncated: Schema.Boolean
+		})
+	]),
+	failure: SparqlToolError,
+	failureMode: "return"
+});
+/**
+* The triples whose subject is the given IRI, as Turtle.
+*
+* @since 0.1.0
+* @category tools
+*/
+const DescribeResource = Tool.make("describe_resource", {
+	description: "Describe a resource: the triples whose subject is the given IRI (one hop), as a Turtle document.",
+	parameters: Schema.Struct({
+		iri: IriParam,
+		limit: Limit
+	}),
+	success: Schema.Struct({
+		turtle: Schema.String,
+		isTruncated: Schema.Boolean
+	}),
+	failure: SparqlToolError,
+	failureMode: "return"
+});
+const Counted = Schema.Array(Schema.Struct({
+	iri: Schema.String,
+	count: Schema.Int
+}));
+/**
+* The classes with instances (`rdf:type`) or declared as `rdfs:Class` /
+* `owl:Class`, by number of instances.
+*
+* @since 0.1.0
+* @category tools
+*/
+const ListClasses = Tool.make("list_classes", {
+	description: "List the classes in the knowledge graph (types in use, and declared rdfs:Class / owl:Class), with their number of instances, most used first.",
+	parameters: Schema.Struct({ limit: Limit }),
+	success: Counted,
+	failure: SparqlToolError,
+	failureMode: "return"
+});
+/**
+* The predicates in use or declared as `rdf:Property` /
+* `owl:ObjectProperty` / `owl:DatatypeProperty`, by number of uses.
+*
+* @since 0.1.0
+* @category tools
+*/
+const ListProperties = Tool.make("list_properties", {
+	description: "List the properties (predicates) in the knowledge graph, in use or declared, with their number of uses, most used first.",
+	parameters: Schema.Struct({ limit: Limit }),
+	success: Counted,
+	failure: SparqlToolError,
+	failureMode: "return"
+});
+/**
+* IRIs whose `rdfs:label` or `skos:prefLabel` contains a string
+* (case-insensitively).
+*
+* @since 0.1.0
+* @category tools
+*/
+const SearchLabels = Tool.make("search_labels", {
+	description: "Find resources by name: IRIs whose rdfs:label or skos:prefLabel contains the given text (case-insensitive).",
+	parameters: Schema.Struct({
+		text: Schema.String.check(Schema.isMinLength(1)).annotate({ description: "The text to look for." }),
+		limit: Limit
+	}),
+	success: Schema.Array(Schema.Struct({
+		iri: Schema.String,
+		label: Schema.String
+	})),
+	failure: SparqlToolError,
+	failureMode: "return"
+});
+/**
+* Runs a SPARQL Update. Only in `toolkitWithUpdate`: the read-only `toolkit`
+* does not offer it.
+*
+* @since 0.1.0
+* @category tools
+*/
+const SparqlUpdate = Tool.make("sparql_update", {
+	description: "Run a SPARQL 1.1 Update (INSERT DATA, DELETE / INSERT … WHERE, …) on the knowledge graph.",
+	parameters: Schema.Struct({ update: Schema.String.annotate({ description: "The SPARQL Update text, with any PREFIX declarations." }) }),
+	success: Schema.Struct({ isApplied: Schema.Boolean }),
+	failure: SparqlToolError,
+	failureMode: "return"
+});
+/**
+* The read-only toolkit: `sparql_query`, `describe_resource`,
+* `list_classes`, `list_properties` and `search_labels`.
+*
+* @since 0.1.0
+* @category toolkits
+*/
+const toolkit = Toolkit.make(SparqlQuery, DescribeResource, ListClasses, ListProperties, SearchLabels);
+/**
+* The read-only toolkit plus `sparql_update`, for agents that may change
+* the graph.
+*
+* @since 0.1.0
+* @category toolkits
+*/
+const toolkitWithUpdate = Toolkit.merge(toolkit, Toolkit.make(SparqlUpdate));
+const toolError = (e) => e instanceof SparqlToolError ? e : new SparqlToolError({ message: e.message });
+const usesService = (query) => {
+	let found = false;
+	transform(translateQuery(query).input, (op) => Match.value(op).pipe(Match.tag("Service", (service) => {
+		found = true;
+		return service;
+	}), Match.orElse(() => op)));
+	return found;
+};
+const take = (stream, rows) => Effect.map(Stream.runCollect(Stream.take(stream, rows + 1)), (all) => ({
+	items: all.slice(0, rows),
+	truncated: all.length > rows
+}));
+const turtleOf = (quads) => serialize(quads.map((q) => quad(q.subject, q.predicate, q.object)));
+const rowsToJson = (variables, rows) => ({
+	head: { vars: [...variables] },
+	results: { bindings: rows.map((row) => Record.map(toRecord(row), termToJson)) }
+});
+const countOf = (row, name) => {
+	const term = getUndefined(row, name);
+	return term !== void 0 && isLiteral(term) ? Number(term.value) : 0;
+};
+/**
+* The handlers of the tools, over the `SparqlEngine` in context.
+*
+* @since 0.1.0
+* @category handlers
+*/
+const handlers = Effect.fnUntraced(function* (options = {}) {
+	const engine = yield* SparqlEngine;
+	const maxRows = options.maxRows ?? 100;
+	const timeout = Duration.fromInputUnsafe(options.timeout ?? "10 seconds");
+	const rowsFor = (limit) => Math.min(limit ?? maxRows, maxRows);
+	const guard = (self) => self.pipe(Effect.timeoutOrElse({
+		duration: timeout,
+		orElse: () => Effect.fail(new SparqlToolError({ message: `the call took longer than ${Duration.format(timeout)}` }))
+	}), Effect.mapError(toolError));
+	const select = (query, rows) => Effect.flatMap(engine.select(query), (result) => take(result.bindings, rows));
+	const sparqlQuery = (query, limit) => guard(Effect.gen(function* () {
+		const ast = yield* parseQuery(query);
+		if (options.federation !== true && usesService(ast)) return yield* new SparqlToolError({ message: "SERVICE (federated) queries are not allowed by this server" });
+		const rows = rowsFor(limit);
+		const result = yield* engine.query(ast);
+		return yield* Match.value(result).pipe(Match.tag("Ask", (ask) => Effect.succeed({
+			type: "ask",
+			isTrue: ask.value
+		})), Match.tag("Select", (selected) => Effect.map(take(selected.bindings, rows), ({ items, truncated }) => ({
+			type: "select",
+			results: rowsToJson(selected.variables.map((v) => v.value), items),
+			isTruncated: truncated
+		}))), Match.tag("Graph", (graph) => Effect.flatMap(take(graph.quads, rows), ({ items, truncated }) => Effect.map(turtleOf(items), (turtle) => ({
+			type: "graph",
+			turtle,
+			isTruncated: truncated
+		})))), Match.exhaustive);
+	}));
+	const describeResource = (iri, limit) => guard(Effect.gen(function* () {
+		const subject = namedNode(iri);
+		const { items, truncated } = yield* select(`SELECT ?p ?o WHERE { ${subject.key} ?p ?o } ORDER BY ?p ?o`, rowsFor(limit));
+		const quads = items.flatMap((row) => {
+			const p = getUndefined(row, "p");
+			const o = getUndefined(row, "o");
+			return p !== void 0 && isNamedNode(p) && o !== void 0 ? [quad(subject, p, o)] : [];
+		});
+		return {
+			turtle: yield* turtleOf(quads),
+			isTruncated: truncated
+		};
+	}));
+	const counted = (query, name, limit) => guard(Effect.map(select(query, rowsFor(limit)), ({ items }) => items.flatMap((row) => {
+		const term = getUndefined(row, name);
+		return term !== void 0 && isNamedNode(term) ? [{
+			iri: term.value,
+			count: countOf(row, "count")
+		}] : [];
+	})));
+	const RDF = "http://www.w3.org/1999/02/22-rdf-syntax-ns#";
+	const RDFS = "http://www.w3.org/2000/01/rdf-schema#";
+	const OWL = "http://www.w3.org/2002/07/owl#";
+	const SKOS = "http://www.w3.org/2004/02/skos/core#";
+	return {
+		sparql_query: ({ query, limit }) => sparqlQuery(query, limit),
+		describe_resource: ({ iri, limit }) => describeResource(iri, limit),
+		list_classes: ({ limit }) => counted(`SELECT ?class (COUNT(?s) AS ?count) WHERE {
+          { ?s a ?class } UNION { ?class a <${RDFS}Class> } UNION { ?class a <${OWL}Class> }
+          FILTER(isIRI(?class))
+        } GROUP BY ?class ORDER BY DESC(?count) ?class`, "class", limit),
+		list_properties: ({ limit }) => counted(`SELECT ?property (COUNT(?s) AS ?count) WHERE {
+          { ?s ?property ?o } UNION { ?property a <${RDF}Property> }
+          UNION { ?property a <${OWL}ObjectProperty> } UNION { ?property a <${OWL}DatatypeProperty> }
+        } GROUP BY ?property ORDER BY DESC(?count) ?property`, "property", limit),
+		search_labels: ({ text, limit }) => guard(Effect.map(select(`SELECT DISTINCT ?resource ?label WHERE {
+              ?resource <${RDFS}label>|<${SKOS}prefLabel> ?label
+              FILTER(isIRI(?resource) && CONTAINS(LCASE(STR(?label)), LCASE(${literal(text).key})))
+            } ORDER BY ?resource ?label`, rowsFor(limit)), ({ items }) => items.flatMap((row) => {
+			const resource = getUndefined(row, "resource");
+			const label = getUndefined(row, "label");
+			return resource !== void 0 && isNamedNode(resource) && label !== void 0 && isLiteral(label) ? [{
+				iri: resource.value,
+				label: label.value
+			}] : [];
+		}))),
+		sparql_update: ({ update }) => guard(Effect.as(engine.update(update), { isApplied: true }))
+	};
+});
+/**
+* The handlers of the read-only `toolkit` as a layer, over the
+* `SparqlEngine` in context.
+*
+* @since 0.1.0
+* @category layers
+*/
+const layer = (options) => toolkit.toLayer(Effect.map(handlers(options), (h) => toolkit.of({
+	sparql_query: h.sparql_query,
+	describe_resource: h.describe_resource,
+	list_classes: h.list_classes,
+	list_properties: h.list_properties,
+	search_labels: h.search_labels
+})));
+/**
+* The handlers of `toolkitWithUpdate` (the read-only tools plus
+* `sparql_update`) as a layer, over the `SparqlEngine` in context.
+*
+* @since 0.1.0
+* @category layers
+*/
+const layerWithUpdate = (options) => toolkitWithUpdate.toLayer(Effect.map(handlers(options), (h) => toolkitWithUpdate.of(h)));
+export { SparqlQuery as a, Tools_exports as c, layerWithUpdate as d, toolkit as f, SearchLabels as i, handlers as l, ListClasses as n, SparqlToolError as o, toolkitWithUpdate as p, ListProperties as r, SparqlUpdate as s, DescribeResource as t, layer as u };
+
+//# sourceMappingURL=Tools-ryxphZbI.mjs.map

package/dist/Tools-ryxphZbI.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tools-ryxphZbI.mjs","names":["Results.JsonResultsSchema","Translate.translateQuery","Turtle.serialize","Term.quad","Bindings.toRecord","Results.termToJson","Bindings.getUndefined","Term.isLiteral","Engine.SparqlEngine","Parser.parseQuery","Term.namedNode","Term.isNamedNode","Term.literal"],"sources":["../src/sparql/ai/Tools.ts"],"sourcesContent":["/**\n * Knowledge-graph tools for `effect/ai`: a `Toolkit` of SPARQL and dataset\n * tools over the `SparqlEngine` service, for `LanguageModel.generateText`\n * and for MCP (see `Mcp`).\n *\n * | Tool                | What it does                                                          |\n * | ------------------- | --------------------------------------------------------------------- |\n * | `sparql_query`      | Runs a read-only SELECT / ASK / CONSTRUCT / DESCRIBE query            |\n * | `describe_resource` | The triples whose subject is an IRI (one hop)                         |\n * | `list_classes`      | Classes in use or declared (`rdfs:Class`, `owl:Class`), with counts   |\n * | `list_properties`   | Predicates in use or declared, with counts                            |\n * | `search_labels`     | IRIs whose `rdfs:label` / `skos:prefLabel` contains a string          |\n * | `sparql_update`     | Runs a SPARQL Update — only in `toolkitWithUpdate`, off by default    |\n *\n * Tool input is model-generated, so it is untrusted: queries are read-only\n * (the query tool only accepts queries; updates need the separate,\n * opt-in tool), every result is capped at `maxRows` rows or triples (and\n * reports whether it was truncated), every call has a `timeout`, and\n * `SERVICE` (federation) is refused unless `federation: true`. Failures are\n * returned to the model as a `SparqlToolError` rather than failing the\n * conversation.\n *\n * @since 0.1.0\n */\nimport * as Duration from 'effect/Duration';\nimport * as Effect from 'effect/Effect';\nimport * as Match from 'effect/Match';\nimport * as Record from 'effect/Record';\nimport * as Schema from 'effect/Schema';\nimport * as Stream from 'effect/Stream';\nimport { Tool, Toolkit } from 'effect/ai';\nimport * as Iri from '../../Iri.ts';\nimport * as Term from '../../Term.ts';\nimport * as Algebra from '../Algebra.ts';\nimport type * as Ast from '../Ast.ts';\nimport * as Bindings from '../Bindings.ts';\nimport * as Engine from '../Engine.ts';\nimport * as Parser from '../Parser.ts';\nimport * as Results from '../Results.ts';\nimport * as Translate from '../Translate.ts';\nimport * as Turtle from '../../turtle/Turtle.ts';\n\n// -----------------------------------------------------------------------------\n// Errors and options\n// -----------------------------------------------------------------------------\n\n/**\n * Why a tool call failed (a syntax error, a refused `SERVICE`, a timeout, …),\n * returned to the model as the tool's result.\n *\n * @since 0.1.0\n * @category errors\n */\nexport class SparqlToolError extends Schema.TaggedError<SparqlToolError>()('SparqlToolError', {\n  message: Schema.String,\n}) {}\n\n/**\n * Limits for the tool handlers.\n *\n * @since 0.1.0\n * @category models\n */\nexport interface ToolOptions {\n  /** The most rows (or triples) a tool returns; a call may ask for fewer. Default 100. */\n  readonly maxRows?: number | undefined;\n  /** How long one call may run. Default 10 seconds. */\n  readonly timeout?: Duration.Input | undefined;\n  /** Allow `SERVICE` (federated) queries. Default `false`. */\n  readonly federation?: boolean | undefined;\n}\n\n// -----------------------------------------------------------------------------\n// Tools\n// -----------------------------------------------------------------------------\n\nconst Limit = Schema.optional(\n  Schema.Int.check(Schema.isGreaterThan(0)).annotate({\n    description: 'The most rows or triples to return (capped by the server).',\n  }),\n);\n\nconst IriParam = Iri.IriSchema.annotate({\n  description: 'An absolute IRI, e.g. http://example.org/alice',\n});\n\n/**\n * Runs a read-only SPARQL query. SELECT results are SPARQL JSON results,\n * ASK a boolean, CONSTRUCT / DESCRIBE a Turtle document.\n *\n * @since 0.1.0\n * @category tools\n */\nexport const SparqlQuery = Tool.make('sparql_query', {\n  description:\n    'Run a read-only SPARQL 1.1 query (SELECT, ASK, CONSTRUCT or DESCRIBE) against the knowledge graph. SELECT returns SPARQL JSON results, ASK a boolean, CONSTRUCT and DESCRIBE a Turtle document. Results are truncated to a row limit.',\n  parameters: Schema.Struct({\n    query: Schema.String.annotate({\n      description: 'The SPARQL query text, with any PREFIX declarations.',\n    }),\n    limit: Limit,\n  }),\n  success: Schema.Union([\n    Schema.Struct({\n      type: Schema.Literal('select'),\n      results: Results.JsonResultsSchema,\n      isTruncated: Schema.Boolean,\n    }),\n    Schema.Struct({ type: Schema.Literal('ask'), isTrue: Schema.Boolean }),\n    Schema.Struct({\n      type: Schema.Literal('graph'),\n      turtle: Schema.String,\n      isTruncated: Schema.Boolean,\n    }),\n  ]),\n  failure: SparqlToolError,\n  failureMode: 'return',\n});\n\n/**\n * The triples whose subject is the given IRI, as Turtle.\n *\n * @since 0.1.0\n * @category tools\n */\nexport const DescribeResource = Tool.make('describe_resource', {\n  description:\n    'Describe a resource: the triples whose subject is the given IRI (one hop), as a Turtle document.',\n  parameters: Schema.Struct({ iri: IriParam, limit: Limit }),\n  success: Schema.Struct({ turtle: Schema.String, isTruncated: Schema.Boolean }),\n  failure: SparqlToolError,\n  failureMode: 'return',\n});\n\nconst Counted = Schema.Array(Schema.Struct({ iri: Schema.String, count: Schema.Int }));\n\n/**\n * The classes with instances (`rdf:type`) or declared as `rdfs:Class` /\n * `owl:Class`, by number of instances.\n *\n * @since 0.1.0\n * @category tools\n */\nexport const ListClasses = Tool.make('list_classes', {\n  description:\n    'List the classes in the knowledge graph (types in use, and declared rdfs:Class / owl:Class), with their number of instances, most used first.',\n  parameters: Schema.Struct({ limit: Limit }),\n  success: Counted,\n  failure: SparqlToolError,\n  failureMode: 'return',\n});\n\n/**\n * The predicates in use or declared as `rdf:Property` /\n * `owl:ObjectProperty` / `owl:DatatypeProperty`, by number of uses.\n *\n * @since 0.1.0\n * @category tools\n */\nexport const ListProperties = Tool.make('list_properties', {\n  description:\n    'List the properties (predicates) in the knowledge graph, in use or declared, with their number of uses, most used first.',\n  parameters: Schema.Struct({ limit: Limit }),\n  success: Counted,\n  failure: SparqlToolError,\n  failureMode: 'return',\n});\n\n/**\n * IRIs whose `rdfs:label` or `skos:prefLabel` contains a string\n * (case-insensitively).\n *\n * @since 0.1.0\n * @category tools\n */\nexport const SearchLabels = Tool.make('search_labels', {\n  description:\n    'Find resources by name: IRIs whose rdfs:label or skos:prefLabel contains the given text (case-insensitive).',\n  parameters: Schema.Struct({\n    text: Schema.String.check(Schema.isMinLength(1)).annotate({\n      description: 'The text to look for.',\n    }),\n    limit: Limit,\n  }),\n  success: Schema.Array(Schema.Struct({ iri: Schema.String, label: Schema.String })),\n  failure: SparqlToolError,\n  failureMode: 'return',\n});\n\n/**\n * Runs a SPARQL Update. Only in `toolkitWithUpdate`: the read-only `toolkit`\n * does not offer it.\n *\n * @since 0.1.0\n * @category tools\n */\nexport const SparqlUpdate = Tool.make('sparql_update', {\n  description:\n    'Run a SPARQL 1.1 Update (INSERT DATA, DELETE / INSERT … WHERE, …) on the knowledge graph.',\n  parameters: Schema.Struct({\n    update: Schema.String.annotate({\n      description: 'The SPARQL Update text, with any PREFIX declarations.',\n    }),\n  }),\n  success: Schema.Struct({ isApplied: Schema.Boolean }),\n  failure: SparqlToolError,\n  failureMode: 'return',\n});\n\n/**\n * The read-only toolkit: `sparql_query`, `describe_resource`,\n * `list_classes`, `list_properties` and `search_labels`.\n *\n * @since 0.1.0\n * @category toolkits\n */\nexport const toolkit = Toolkit.make(\n  SparqlQuery,\n  DescribeResource,\n  ListClasses,\n  ListProperties,\n  SearchLabels,\n);\n\n/**\n * The read-only toolkit plus `sparql_update`, for agents that may change\n * the graph.\n *\n * @since 0.1.0\n * @category toolkits\n */\nexport const toolkitWithUpdate = Toolkit.merge(toolkit, Toolkit.make(SparqlUpdate));\n\n// -----------------------------------------------------------------------------\n// Handlers\n// -----------------------------------------------------------------------------\n\nconst toolError = (e: { readonly message: string }): SparqlToolError =>\n  e instanceof SparqlToolError ? e : new SparqlToolError({ message: e.message });\n\n// Whether a query's algebra has a `SERVICE` (federated) pattern.\nconst usesService = (query: Ast.Query): boolean => {\n  let found = false;\n  Algebra.transform(Translate.translateQuery(query).input, (op) =>\n    Match.value(op).pipe(\n      Match.tag('Service', (service) => {\n        found = true;\n        return service;\n      }),\n      Match.orElse(() => op),\n    ),\n  );\n  return found;\n};\n\n// At most `rows` elements of a stream, and whether there were more.\nconst take = <A, E>(stream: Stream.Stream<A, E>, rows: number) =>\n  Effect.map(Stream.runCollect(Stream.take(stream, rows + 1)), (all) => ({\n    items: all.slice(0, rows),\n    truncated: all.length > rows,\n  }));\n\nconst turtleOf = (quads: ReadonlyArray<Term.Quad>) =>\n  Turtle.serialize(quads.map((q) => Term.quad(q.subject, q.predicate, q.object)));\n\nconst rowsToJson = (\n  variables: ReadonlyArray<string>,\n  rows: ReadonlyArray<Bindings.Bindings>,\n): Results.JsonResults => ({\n  head: { vars: [...variables] },\n  results: {\n    bindings: rows.map((row) => Record.map(Bindings.toRecord(row), Results.termToJson)),\n  },\n});\n\nconst countOf = (row: Bindings.Bindings, name: string): number => {\n  const term = Bindings.getUndefined(row, name);\n  return term !== undefined && Term.isLiteral(term) ? Number(term.value) : 0;\n};\n\n/**\n * The handlers of the tools, over the `SparqlEngine` in context.\n *\n * @since 0.1.0\n * @category handlers\n */\nexport const handlers = Effect.fnUntraced(function* (options: ToolOptions = {}) {\n  const engine = yield* Engine.SparqlEngine;\n  const maxRows = options.maxRows ?? 100;\n  const timeout = Duration.fromInputUnsafe(options.timeout ?? '10 seconds');\n  const rowsFor = (limit: number | undefined) => Math.min(limit ?? maxRows, maxRows);\n\n  // Every call: a timeout, and any failure as a `SparqlToolError`.\n  const guard = <A, E extends { readonly message: string }, R>(\n    self: Effect.Effect<A, E, R>,\n  ): Effect.Effect<A, SparqlToolError, R> =>\n    self.pipe(\n      Effect.timeoutOrElse({\n        duration: timeout,\n        orElse: () =>\n          Effect.fail(\n            new SparqlToolError({\n              message: `the call took longer than ${Duration.format(timeout)}`,\n            }),\n          ),\n      }),\n      Effect.mapError(toolError),\n    );\n\n  const select = (query: string, rows: number) =>\n    Effect.flatMap(engine.select(query), (result) => take(result.bindings, rows));\n\n  const sparqlQuery = (query: string, limit: number | undefined) =>\n    guard(\n      Effect.gen(function* () {\n        const ast = yield* Parser.parseQuery(query);\n        if (options.federation !== true && usesService(ast)) {\n          return yield* new SparqlToolError({\n            message: 'SERVICE (federated) queries are not allowed by this server',\n          });\n        }\n        const rows = rowsFor(limit);\n        const result = yield* engine.query(ast);\n        return yield* Match.value(result).pipe(\n          Match.tag('Ask', (ask) => Effect.succeed({ type: 'ask' as const, isTrue: ask.value })),\n          Match.tag('Select', (selected) =>\n            Effect.map(take(selected.bindings, rows), ({ items, truncated }) => ({\n              type: 'select' as const,\n              results: rowsToJson(\n                selected.variables.map((v) => v.value),\n                items,\n              ),\n              isTruncated: truncated,\n            })),\n          ),\n          Match.tag('Graph', (graph) =>\n            Effect.flatMap(take(graph.quads, rows), ({ items, truncated }) =>\n              Effect.map(turtleOf(items), (turtle) => ({\n                type: 'graph' as const,\n                turtle,\n                isTruncated: truncated,\n              })),\n            ),\n          ),\n          Match.exhaustive,\n        );\n      }),\n    );\n\n  const describeResource = (iri: string, limit: number | undefined) =>\n    guard(\n      Effect.gen(function* () {\n        const subject = Term.namedNode(iri);\n        const { items, truncated } = yield* select(\n          `SELECT ?p ?o WHERE { ${subject.key} ?p ?o } ORDER BY ?p ?o`,\n          rowsFor(limit),\n        );\n        const quads = items.flatMap((row) => {\n          const p = Bindings.getUndefined(row, 'p');\n          const o = Bindings.getUndefined(row, 'o');\n          return p !== undefined && Term.isNamedNode(p) && o !== undefined\n            ? [Term.quad(subject, p, o)]\n            : [];\n        });\n        return { turtle: yield* turtleOf(quads), isTruncated: truncated };\n      }),\n    );\n\n  const counted = (query: string, name: string, limit: number | undefined) =>\n    guard(\n      Effect.map(select(query, rowsFor(limit)), ({ items }) =>\n        items.flatMap((row) => {\n          const term = Bindings.getUndefined(row, name);\n          return term !== undefined && Term.isNamedNode(term)\n            ? [{ iri: term.value, count: countOf(row, 'count') }]\n            : [];\n        }),\n      ),\n    );\n\n  const RDF = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#';\n  const RDFS = 'http://www.w3.org/2000/01/rdf-schema#';\n  const OWL = 'http://www.w3.org/2002/07/owl#';\n  const SKOS = 'http://www.w3.org/2004/02/skos/core#';\n\n  return {\n    sparql_query: ({\n      query,\n      limit,\n    }: {\n      readonly query: string;\n      readonly limit?: number | undefined;\n    }) => sparqlQuery(query, limit),\n    describe_resource: ({\n      iri,\n      limit,\n    }: {\n      readonly iri: string;\n      readonly limit?: number | undefined;\n    }) => describeResource(iri, limit),\n    list_classes: ({ limit }: { readonly limit?: number | undefined }) =>\n      counted(\n        `SELECT ?class (COUNT(?s) AS ?count) WHERE {\n          { ?s a ?class } UNION { ?class a <${RDFS}Class> } UNION { ?class a <${OWL}Class> }\n          FILTER(isIRI(?class))\n        } GROUP BY ?class ORDER BY DESC(?count) ?class`,\n        'class',\n        limit,\n      ),\n    list_properties: ({ limit }: { readonly limit?: number | undefined }) =>\n      counted(\n        `SELECT ?property (COUNT(?s) AS ?count) WHERE {\n          { ?s ?property ?o } UNION { ?property a <${RDF}Property> }\n          UNION { ?property a <${OWL}ObjectProperty> } UNION { ?property a <${OWL}DatatypeProperty> }\n        } GROUP BY ?property ORDER BY DESC(?count) ?property`,\n        'property',\n        limit,\n      ),\n    search_labels: ({\n      text,\n      limit,\n    }: {\n      readonly text: string;\n      readonly limit?: number | undefined;\n    }) =>\n      guard(\n        Effect.map(\n          select(\n            `SELECT DISTINCT ?resource ?label WHERE {\n              ?resource <${RDFS}label>|<${SKOS}prefLabel> ?label\n              FILTER(isIRI(?resource) && CONTAINS(LCASE(STR(?label)), LCASE(${Term.literal(text).key})))\n            } ORDER BY ?resource ?label`,\n            rowsFor(limit),\n          ),\n          ({ items }) =>\n            items.flatMap((row) => {\n              const resource = Bindings.getUndefined(row, 'resource');\n              const label = Bindings.getUndefined(row, 'label');\n              return resource !== undefined &&\n                Term.isNamedNode(resource) &&\n                label !== undefined &&\n                Term.isLiteral(label)\n                ? [{ iri: resource.value, label: label.value }]\n                : [];\n            }),\n        ),\n      ),\n    sparql_update: ({ update }: { readonly update: string }) =>\n      guard(Effect.as(engine.update(update), { isApplied: true })),\n  };\n});\n\n/**\n * The handlers of the read-only `toolkit` as a layer, over the\n * `SparqlEngine` in context.\n *\n * @since 0.1.0\n * @category layers\n */\nexport const layer = (options?: ToolOptions) =>\n  toolkit.toLayer(\n    Effect.map(handlers(options), (h) =>\n      toolkit.of({\n        sparql_query: h.sparql_query,\n        describe_resource: h.describe_resource,\n        list_classes: h.list_classes,\n        list_properties: h.list_properties,\n        search_labels: h.search_labels,\n      }),\n    ),\n  );\n\n/**\n * The handlers of `toolkitWithUpdate` (the read-only tools plus\n * `sparql_update`) as a layer, over the `SparqlEngine` in context.\n *\n * @since 0.1.0\n * @category layers\n */\nexport const layerWithUpdate = (options?: ToolOptions) =>\n  toolkitWithUpdate.toLayer(Effect.map(handlers(options), (h) => toolkitWithUpdate.of(h)));\n"],"mappings":"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"}

package/dist/Translate-B0YKKANS.d.mts

@@ -0,0 +1,37 @@
+import { _ as Expression, q as Query, w as GroupPattern } from "./Ast-vcw2W-lf.mjs";
+import { S as Query$1, g as Operation, o as Expression$1 } from "./Algebra-uGsIEOUA.mjs";
+declare namespace Translate_d_exports {
+  export { simplify, translateExpression, translatePattern, translateQuery };
+}
+/**
+ * Removes joins with the empty BGP (`Join(Z, A)` → `A`).
+ *
+ * @since 0.1.0
+ * @category simplification
+ */
+declare const simplify: (op: Operation) => Operation;
+/**
+ * Translates a query to the algebra.
+ *
+ * @since 0.1.0
+ * @category translation
+ */
+declare const translateQuery: (query: Query) => Query$1;
+/**
+ * Translates a group graph pattern (e.g. the `WHERE` clause of an update) to
+ * the algebra.
+ *
+ * @since 0.1.0
+ * @category translation
+ */
+declare const translatePattern: (pattern: GroupPattern) => Operation;
+/**
+ * Translates an expression (which must not contain aggregates) to the
+ * algebra.
+ *
+ * @since 0.1.0
+ * @category translation
+ */
+declare const translateExpression: (expression: Expression) => Expression$1;
+export { translateQuery as a, translatePattern as i, simplify as n, translateExpression as r, Translate_d_exports as t };
+//# sourceMappingURL=Translate-B0YKKANS.d.mts.map