Skip to content

Commit

Permalink
docs: improve openapi documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@zAlweNy26
zAlweNy26 committed Oct 13, 2024
1 parent 8ebf0b8 commit 6d812e1
Show file tree
Hide file tree
Showing 6 changed files with 190 additions and 83 deletions.
106 changes: 102 additions & 4 deletions src/context.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,94 @@ export const swaggerTags = {

const jsonLiterals = t.Union([t.String(), t.Number(), t.Boolean(), t.Null()])

export const memoryMessage = t.Object({
role: t.Union([t.Literal('AI'), t.Literal('User')]),
what: t.String(),
who: t.String(),
when: t.Number(),
why: t.Optional(t.Object({
input: t.String(),
intermediateSteps: t.Array(t.Object({
tool: t.String(),
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())),
})),
}, {
$id: 'memoryMessage',
title: 'Memory Message',
description: 'Content object saved in memory',
})

export const chatMessage = t.Union([
t.Object({
type: t.Literal('error'),
name: t.String(),
description: t.String(),
}),
t.Object({
type: t.Union([t.Literal('token'), t.Literal('notification')]),
content: t.String(),
}),
t.Intersect([
t.Object({
type: t.Literal('chat'),
}),
memoryMessage,
]),
], {
$id: 'chatMessage',
title: 'Chat Message',
description: 'Message object received from the cat',
})

export const memoryRecall = t.Object({
query: t.Object({
text: t.String(),
vector: t.Array(t.Number()),
}),
vectors: t.Object({
embedder: t.String(),
collections: t.Record(t.String(), t.Array(t.Object({
id: t.String(),
vector: t.Array(t.Number()),
score: t.Number(),
pageContent: t.String(),
metadata: t.Optional(t.Record(t.String(), t.Any())),
}))),
}),
}, {
title: 'Recalled memories',
description: 'Recalled memories from memory collections',
examples: [{
query: {
text: 'Hello, world!',
vector: [0.1, 0.2, 0.3],
},
vectors: {
embedder: 'OpenAIEmbedder',
collections: {
declarative: [],
procedural: [],
episodic: [
{
id: '1da746f8-a832-4a45-a120-4549e17a1df7',
score: 0.8,
vector: [0.1, 0.2, 0.3],
pageContent: 'Hello, John!',
metadata: {
source: 'user',
when: 1712950290994,
},
},
],
},
},
}],
})

export const modelInfo = t.Object({
id: t.String(),
name: t.String(),
Expand Down Expand Up @@ -142,7 +230,7 @@ export const serverContext = new Elysia({ name: 'server-context' }).use(httpErro
db,
}).onBeforeHandle({ as: 'scoped' }, ({ headers, path, HttpError }) => {
const apiKey = headers.token, realKey = parsedEnv.apiKey
if (path.startsWith('/docs')) return
if (path.startsWith('/docs') || path.startsWith('/assets')) return
if (realKey && realKey !== apiKey)
throw HttpError.Unauthorized('Invalid API key')
}).derive({ as: 'global' }, ({ headers }) => {
Expand All @@ -153,7 +241,7 @@ export const serverContext = new Elysia({ name: 'server-context' }).use(httpErro
examples: [{ key: 'value' }],
$id: 'GenericObject',
title: 'Generic Object',
description: 'A generic key-value object',
description: 'Generic key-value object',
}),
json: t.Union([jsonLiterals, t.Array(jsonLiterals), t.Record(t.String(), jsonLiterals)], {
examples: [
Expand All @@ -164,7 +252,7 @@ export const serverContext = new Elysia({ name: 'server-context' }).use(httpErro
],
$id: 'GenericJson',
title: 'Generic JSON',
description: 'A generic object representing all JSON possible values',
description: 'Generic object representing all JSON possible values',
}),
customSetting: t.Object({
name: t.String(),
Expand All @@ -173,8 +261,18 @@ export const serverContext = new Elysia({ name: 'server-context' }).use(httpErro
examples: [{ name: 'key', value: 'value' }],
$id: 'CustomSetting',
title: 'Custom Setting',
description: 'A custom setting for the cat',
description: 'Custom setting for the cat',
}),
chatMessage,
memoryMessage,
chatHistory: t.Object({
history: t.Array(t.Ref(memoryMessage)),
}, {
$id: 'ChatHistory',
title: 'Chat History',
description: 'Chat messages history',
}),
memoryRecall,
modelInfo,
pluginManifest,
pluginInfo,
Expand Down
2 changes: 1 addition & 1 deletion src/errors.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ export const httpError = new Elysia({ name: 'http-error' })
}],
$id: 'GenericError',
title: 'Generic Error',
description: 'The model for an HTTP error response',
description: 'Generic HTTP error response',
}),
})
.onError({ as: 'global' }, ({ code, error, set }) => {
Expand Down
28 changes: 20 additions & 8 deletions src/routes/general.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,14 @@ export const generalRoutes = new Elysia({
status: t.String(),
version: t.String(),
protected: t.Boolean(),
}, {
title: 'Server Status',
description: 'Current server status',
examples: [{
status: 'We\'re all mad here, dear!',
version: '1.0.0',
protected: false,
}],
}),
400: 'error',
},
Expand All @@ -86,16 +94,16 @@ export const generalRoutes = new Elysia({
description: 'Get a response from the Cheshire Cat using the RAG.',
},
response: {
200: t.Record(t.String(), t.Any()),
200: 'chatMessage',
400: 'error',
},
}).post('/pure', async function* ({ stray, body, query }) {
const { stream } = query
if (stream) {
const res = await stray.llm(body.messages, stream)
for await (const chunk of res) yield normalizeMessageChunks(chunk)
}
return normalizeMessageChunks(await stray.llm(body.messages))

if (!stream) return normalizeMessageChunks(await stray.llm(body.messages))

const res = await stray.llm(body.messages, stream)
for await (const chunk of res) yield normalizeMessageChunks(chunk)
}, {
body: t.Object({
messages: t.Array(t.String(), { default: ['Hello world'] }),
Expand All @@ -108,7 +116,7 @@ export const generalRoutes = new Elysia({
description: 'Get a pure LLM response from the Cheshire Cat.',
},
response: {
200: t.Record(t.String(), t.Any()),
200: t.Union([t.String(), t.Record(t.String(), t.Any())]),
400: 'error',
},
}).post('/embed', async ({ stray, body }) => {
Expand All @@ -123,7 +131,11 @@ export const generalRoutes = new Elysia({
description: 'Get a pure Embedder response from the Cheshire Cat.',
},
response: {
200: t.Array(t.Number()),
200: t.Array(t.Number(), {
title: 'Embedding',
description: 'Embedding response',
examples: [[0.1, 0.2, 0.3]],
}),
400: 'error',
},
})
106 changes: 41 additions & 65 deletions src/routes/memory.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,48 +50,7 @@ export const memoryRoutes = new Elysia({
k: t.Number({ default: 10 }),
}),
response: {
200: t.Object({
query: t.Object({
text: t.String(),
vector: t.Array(t.Number()),
}),
vectors: t.Object({
embedder: t.String(),
collections: t.Record(t.String(), t.Array(t.Object({
id: t.String(),
vector: t.Array(t.Number()),
score: t.Number(),
pageContent: t.String(),
metadata: t.Optional(t.Record(t.String(), t.Any())),
}))),
}, {
examples: [{
query: {
text: 'Hello, world!',
vector: [0.1, 0.2, 0.3],
},
vectors: {
embedder: 'OpenAIEmbedder',
collections: {
declarative: [],
procedural: [],
episodic: [
{
id: '1da746f8-a832-4a45-a120-4549e17a1df7',
score: 0.8,
vector: [0.1, 0.2, 0.3],
pageContent: 'Hello, John!',
metadata: {
source: 'user',
when: 1712950290994,
},
},
],
},
},
}],
}),
}),
200: 'memoryRecall',
500: 'error',
},
}).get('/collections', async () => {
Expand Down Expand Up @@ -119,6 +78,8 @@ export const memoryRoutes = new Elysia({
size: t.Number(),
})),
}, {
title: 'Collections',
description: 'List of available collections and their sizes',
examples: [{
collections: [
{
Expand Down Expand Up @@ -155,7 +116,7 @@ export const memoryRoutes = new Elysia({
summary: 'Wipe collections',
},
response: {
204: t.Void(),
204: t.Void({ title: 'Collections wiped', description: 'Collections wiped successfully' }),
500: 'error',
},
}).delete('/collections/:collectionId', async ({ mh, params, log, HttpError }) => {
Expand All @@ -180,7 +141,7 @@ export const memoryRoutes = new Elysia({
collectionId: t.String(),
}),
response: {
204: t.Void(),
204: t.Void({ title: 'Collection wiped', description: 'Collection wiped successfully' }),
404: 'error',
500: 'error',
},
Expand Down Expand Up @@ -236,6 +197,27 @@ export const memoryRoutes = new Elysia({
}],
}),
})),
}, {
title: 'Documents',
description: 'List of documents in the collection',
examples: [{
documents: [
{
id: '1da746f8-a832-4a45-a120-4549e17a1df7',
pageContent: 'Hello, John!',
metadata: {
source: 'user',
},
},
{
id: '1da746f8-a832-4a45-a120-4549e17a1df8',
pageContent: 'Hello, Jane!',
metadata: {
source: 'user',
},
},
],
}],
}),
404: 'error',
500: 'error',
Expand Down Expand Up @@ -269,7 +251,7 @@ export const memoryRoutes = new Elysia({
}],
}),
response: {
204: t.Void(),
204: t.Void({ title: 'Documents wiped', description: 'Documents wiped successfully' }),
404: 'error',
500: 'error',
},
Expand All @@ -296,7 +278,7 @@ export const memoryRoutes = new Elysia({
pointId: t.String(),
}),
response: {
204: t.Void(),
204: t.Void({ title: 'Point wiped', description: 'Point wiped successfully' }),
404: 'error',
500: 'error',
},
Expand Down Expand Up @@ -329,6 +311,16 @@ export const memoryRoutes = new Elysia({
id: t.String(),
vector: t.Array(t.Number()),
payload: t.Record(t.String(), t.Any()),
}, {
title: 'Memory Point',
description: 'Point in memory',
examples: [{
id: '1da746f8-a832-4a45-a120-4549e17a1df7',
vector: [0.1, 0.2, 0.3],
payload: {
source: 'user',
},
}],
}),
404: 'error',
500: 'error',
Expand All @@ -343,23 +335,7 @@ export const memoryRoutes = new Elysia({
summary: 'Get conversation history',
},
response: {
200: t.Object({
history: t.Array(t.Object({
what: t.String(),
who: t.String(),
when: t.Number(),
why: t.Optional(t.Object({
input: t.String(),
intermediateSteps: t.Array(t.Object({
tool: t.String(),
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())),
})),
})),
}),
200: 'chatHistory',
},
}).delete('/history', ({ stray }) => {
stray.clearHistory()
Expand All @@ -369,7 +345,7 @@ export const memoryRoutes = new Elysia({
summary: 'Wipe conversation history',
},
response: {
204: t.Void(),
204: t.Void({ title: 'History wiped', description: 'History wiped successfully' }),
},
}).put('/history', ({ stray, body }) => {
stray.addHistory(body)
Expand All @@ -385,6 +361,6 @@ export const memoryRoutes = new Elysia({
when: t.Number(),
})),
response: {
204: t.Void(),
204: t.Void({ title: 'History added', description: 'History added successfully' }),
},
})
Loading

0 comments on commit 6d812e1

Please sign in to comment.