docs: improve documentation

src/context.ts

@@ -52,8 +52,15 @@ export const memoryMessage = t.Object({
 			input: t.Union([t.String(), t.Null()]),
 			observation: t.String(),
 		})),
-		memory: t.Optional(t.Record(t.String(), t.Any())),
-		interactions: t.Optional(t.Record(t.String(), t.Any())),
+		memory: t.Optional(t.Intersect([
+			t.Object({
+				episodic: t.Array(t.Record(t.String(), t.Any())),
+				declarative: t.Array(t.Record(t.String(), t.Any())),
+				procedural: t.Array(t.Record(t.String(), t.Any())),
+			}),
+			t.Record(t.String(), t.Array(t.Record(t.String(), t.Any()))),
+		])),
+		interactions: t.Optional(t.Array(t.Record(t.String(), t.Any()))),
 	})),
 }, {
 	$id: 'memoryMessage',
@@ -287,7 +294,7 @@ export const serverContext = new Elysia({ name: 'server-context' }).use(httpErro
 	}),
 	pluginsInfo: t.Object({
 		installed: t.Array(t.Ref(pluginInfo)),
-		registry: t.Array(t.Ref(pluginInfo)),
+		registry: t.Array(t.Pick(pluginInfo, ['id', 'manifest'])),
 	}, {
 		$id: 'PluginsInfo',
 		title: 'Plugins Information',

src/looking_glass/stray-cat.ts

@@ -139,6 +139,7 @@ export class StrayCat {
 	 * Processes the user message and returns the response.
 	 * @param msg The message to send.
 	 * @param save Whether to save the message or not in the chat history (default: true).
+	 * @param returnWhy Whether to return the 'why' field in the response (default: true).
 	 * @returns The response message.
 	 */
 	async run(msg: Message, save = true, returnWhy = true): Promise<WSMessage> {

src/routes/embedder.ts

@@ -39,7 +39,7 @@ export const embedderRoutes = new Elysia({
 		value,
 	}
 }, {
-	params: t.Object({ embedderId: t.String() }),
+	params: t.Object({ embedderId: t.String({ title: 'Embedder ID', description: 'ID of one of the available embedders' }) }),
 	detail: {
 		description: 'Get settings and schema of the specified embedder.',
 		summary: 'Get embedder settings',
@@ -75,7 +75,7 @@ export const embedderRoutes = new Elysia({
 		value: parsed.data,
 	}
 }, {
-	params: t.Object({ embedderId: t.String() }),
+	params: t.Object({ embedderId: t.String({ title: 'Embedder ID', description: 'ID of one of the available embedders' }) }),
 	body: 'generic',
 	detail: {
 		description: 'Upsert the specified embedder setting.',

src/routes/general.ts

@@ -83,11 +83,23 @@ export const generalRoutes = new Elysia({
 	return res
 }, {
 	body: t.Object({
-		text: t.String({ default: 'Hello world' }),
+		text: t.String({
+			title: 'Text',
+			description: 'The text to send to the Cheshire Cat',
+			default: 'Hello world',
+		}),
 	}),
 	query: t.Object({
-		save: t.Boolean({ default: true }),
-		why: t.Boolean({ default: true }),
+		save: t.Boolean({
+			title: 'Save',
+			description: 'Whether to save the message in the memory',
+			default: true,
+		}),
+		why: t.Boolean({
+			title: 'Why',
+			description: 'Whether to include the reasoning in the response',
+			default: true,
+		}),
 	}),
 	detail: {
 		summary: 'Chat',
@@ -106,10 +118,18 @@ export const generalRoutes = new Elysia({
 	for await (const chunk of res) yield normalizeMessageChunks(chunk)
 }, {
 	body: t.Object({
-		messages: t.Array(t.String(), { default: ['Hello world'] }),
+		messages: t.Array(t.String(), {
+			title: 'Messages',
+			description: 'The messages to send to the Cheshire Cat',
+			default: ['Hello world'],
+		}),
 	}),
 	query: t.Object({
-		stream: t.Boolean({ default: true }),
+		stream: t.Boolean({
+			title: 'Stream',
+			description: 'Whether to stream the response',
+			default: true,
+		}),
 	}),
 	detail: {
 		summary: 'Pure llm',
@@ -124,7 +144,11 @@ export const generalRoutes = new Elysia({
 	return res
 }, {
 	body: t.Object({
-		text: t.String({ default: 'Hello world' }),
+		text: t.String({
+			title: 'Text',
+			description: 'The text to embed using the current selected embedder',
+			default: 'Hello world',
+		}),
 	}),
 	detail: {
 		summary: 'Pure embed',

src/routes/llm.ts

@@ -39,7 +39,7 @@ export const llmRoutes = new Elysia({
 		value,
 	}
 }, {
-	params: t.Object({ llmId: t.String() }),
+	params: t.Object({ llmId: t.String({ title: 'LLM ID', description: 'ID of one of the available LLMs' }) }),
 	detail: {
 		description: 'Get settings and schema of the specified Large Language Model.',
 		summary: 'Get LLM settings',
@@ -75,7 +75,7 @@ export const llmRoutes = new Elysia({
 		value: parsed.data,
 	}
 }, {
-	params: t.Object({ llmId: t.String() }),
+	params: t.Object({ llmId: t.String({ title: 'LLM ID', description: 'ID of one of the available LLMs' }) }),
 	body: 'generic',
 	detail: {
 		description: 'Upsert the specified Large Language Model setting.',

src/routes/memory.ts

@@ -1,6 +1,6 @@
 import type { MemoryDocument } from '@dto/message.ts'
 import type { FilterMatch } from '@dto/vector-memory.ts'
-import { serverContext, swaggerTags } from '@/context'
+import { memoryMessage, serverContext, swaggerTags } from '@/context'
 import { cheshireCat as cat } from '@lg/cheshire-cat.ts'
 import { Elysia, t } from 'elysia'
 
@@ -46,8 +46,8 @@ export const memoryRoutes = new Elysia({
 		summary: 'Recall memories',
 	},
 	query: t.Object({
-		text: t.String(),
-		k: t.Number({ default: 10 }),
+		text: t.String({ title: 'Text', description: 'Text to search for' }),
+		k: t.Number({ title: 'K', description: 'Number of memories to extract', default: 10 }),
 	}),
 	response: {
 		200: 'memoryRecall',
@@ -99,12 +99,13 @@ export const memoryRoutes = new Elysia({
 		}),
 		500: 'error',
 	},
-}).delete('/collections', async ({ mh, log, HttpError }) => {
+}).delete('/collections', async ({ mh, log, HttpError, set }) => {
 	try {
 		const collections = Object.keys(cat.vectorMemory.collections)
 		for (const collection of collections) await cat.vectorMemory.db.deleteCollection(collection)
 		await cat.loadMemory()
 		await mh.findPlugins()
+		set.status = 204
 	}
 	catch (error) {
 		log.error(error)
@@ -119,14 +120,15 @@ export const memoryRoutes = new Elysia({
 		204: t.Void({ title: 'Collections wiped', description: 'Collections wiped successfully' }),
 		500: 'error',
 	},
-}).delete('/collections/:collectionId', async ({ mh, params, log, HttpError }) => {
+}).delete('/collections/:collectionId', async ({ mh, params, log, HttpError, set }) => {
 	const id = params.collectionId
 	try {
 		const collections = Object.keys(cat.vectorMemory.collections)
 		if (!collections.includes(id)) throw HttpError.NotFound('Collection not found.')
 		await cat.vectorMemory.db.deleteCollection(id)
 		await cat.loadMemory()
 		await mh.findPlugins()
+		set.status = 204
 	}
 	catch (error) {
 		log.error(error)
@@ -138,7 +140,7 @@ export const memoryRoutes = new Elysia({
 		summary: 'Wipe single collection',
 	},
 	params: t.Object({
-		collectionId: t.String(),
+		collectionId: t.String({ title: 'Collection ID', description: 'ID of the collection to wipe' }),
 	}),
 	response: {
 		204: t.Void({ title: 'Collection wiped', description: 'Collection wiped successfully' }),
@@ -172,11 +174,13 @@ export const memoryRoutes = new Elysia({
 			url: 'https://qdrant.tech/documentation/concepts/filtering/#filtering-conditions',
 		},
 	},
-	params: t.Object({ collectionId: t.String() }),
+	params: t.Object({ collectionId: t.String({ title: 'Collection ID', description: 'ID of the collection from which to get the documents' }) }),
 	query: t.Object({
-		k: t.Number({ default: 10 }),
+		k: t.Number({ title: 'K', description: 'Number of documents to retrieve', default: 10 }),
 	}),
 	body: t.Record(t.String(), t.Any(), {
+		title: 'Metadata filter',
+		description: 'Filter documents by metadata',
 		examples: [{
 			source: {
 				any: ['user'],
@@ -222,12 +226,13 @@ export const memoryRoutes = new Elysia({
 		404: 'error',
 		500: 'error',
 	},
-}).delete('/collections/:collectionId/documents', async ({ params, body, log, HttpError }) => {
+}).delete('/collections/:collectionId/documents', async ({ params, body, log, HttpError, set }) => {
 	const id = params.collectionId
 	try {
 		const collections = Object.keys(cat.vectorMemory.collections)
 		if (!collections.includes(id)) throw HttpError.NotFound('Collection not found.')
 		await cat.vectorMemory.collections[id]!.deletePointsByMetadata(body)
+		set.status = 204
 	}
 	catch (error) {
 		log.error(error)
@@ -242,7 +247,7 @@ export const memoryRoutes = new Elysia({
 			url: 'https://qdrant.tech/documentation/concepts/filtering/#filtering-conditions',
 		},
 	},
-	params: t.Object({ collectionId: t.String() }),
+	params: t.Object({ collectionId: t.String({ title: 'Collection ID', description: 'ID of the collection whose documents must be wiped' }) }),
 	body: t.Record(t.String(), t.Any(), {
 		examples: [{
 			source: {
@@ -255,14 +260,15 @@ export const memoryRoutes = new Elysia({
 		404: 'error',
 		500: 'error',
 	},
-}).delete('/collections/:collectionId/point/:pointId', async ({ params, log, HttpError }) => {
+}).delete('/collections/:collectionId/point/:pointId', async ({ params, log, HttpError, set }) => {
 	const { collectionId, pointId } = params
 	try {
 		const collections = Object.keys(cat.vectorMemory.collections)
 		if (!collections.includes(collectionId)) throw HttpError.NotFound('Collection not found.')
 		const points = await cat.vectorMemory.db.retrieve(collectionId, { ids: [pointId] })
 		if (points.length === 0) throw HttpError.NotFound('Point not found.')
 		await cat.vectorMemory.collections[collectionId]?.deletePoints([pointId])
+		set.status = 204
 	}
 	catch (error) {
 		log.error(error)
@@ -274,8 +280,8 @@ export const memoryRoutes = new Elysia({
 		summary: 'Wipe memory point',
 	},
 	params: t.Object({
-		collectionId: t.String(),
-		pointId: t.String(),
+		collectionId: t.String({ title: 'Collection ID', description: 'ID of the collection whose point must be deleted' }),
+		pointId: t.String({ title: 'Point ID', description: 'ID of the point to delete' }),
 	}),
 	response: {
 		204: t.Void({ title: 'Point wiped', description: 'Point wiped successfully' }),
@@ -303,8 +309,8 @@ export const memoryRoutes = new Elysia({
 		summary: 'Get memory point',
 	},
 	params: t.Object({
-		collectionId: t.String(),
-		pointId: t.String(),
+		collectionId: t.String({ title: 'Collection ID', description: 'ID of the collection from which to get the point' }),
+		pointId: t.String({ title: 'Point ID', description: 'ID of the point to retrieve' }),
 	}),
 	response: {
 		200: t.Object({
@@ -337,8 +343,9 @@ export const memoryRoutes = new Elysia({
 	response: {
 		200: 'chatHistory',
 	},
-}).delete('/history', ({ stray }) => {
+}).delete('/history', ({ stray, set }) => {
 	stray.clearHistory()
+	set.status = 204
 }, {
 	detail: {
 		description: 'Delete the specified user\'s conversation history from working memory.',
@@ -347,19 +354,30 @@ export const memoryRoutes = new Elysia({
 	response: {
 		204: t.Void({ title: 'History wiped', description: 'History wiped successfully' }),
 	},
-}).put('/history', ({ stray, body }) => {
-	stray.addHistory(body)
+}).put('/history', ({ stray, body, set }) => {
+	stray.addHistory(body.history)
+	set.status = 204
 }, {
 	detail: {
 		description: 'Add conversation history messages to the specified user\'s working memory.',
 		summary: 'Add conversation history messages',
 	},
-	body: t.Array(t.Object({
-		role: t.Union([t.Literal('AI'), t.Literal('User')]),
-		what: t.String(),
-		who: t.String(),
-		when: t.Number(),
-	})),
+	body: t.Object({
+		history: t.Array(t.Omit(memoryMessage, ['why'])),
+	}, {
+		title: 'History Messages',
+		description: 'History messages',
+		examples: [{
+			history: [
+				{
+					role: 'User',
+					what: 'Hello, world!',
+					when: 1712950292521,
+					who: 'evi2734v',
+				},
+			],
+		}],
+	}),
 	response: {
 		204: t.Void({ title: 'History added', description: 'History added successfully' }),
 	},