llmspy 0.0.0-stage → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,201 @@
1
+ import { DatabaseSync } from 'node:sqlite';
2
+ import { matchesFilters, matchesSearch, toSummary, } from './summary.js';
3
+ const DAY_MS = 24 * 60 * 60 * 1000;
4
+ /** Set on a call that was still running when LLMSpy last stopped. */
5
+ export const INTERRUPTED = 'interrupted: LLMSpy stopped before the call ended';
6
+ /**
7
+ * `LLMSPY_RETENTION_DAYS`: a whole number of days, 0 to keep every call.
8
+ * Unset means 7.
9
+ */
10
+ export function parseRetentionDays(value) {
11
+ if (value === undefined || value === '')
12
+ return 7;
13
+ if (!/^\d+$/.test(value)) {
14
+ throw new Error(`LLMSPY_RETENTION_DAYS must be a whole number of days (0 keeps every call), not "${value}".`);
15
+ }
16
+ return Number(value);
17
+ }
18
+ /**
19
+ * Captured calls in SQLite, newest first. A running call is also kept in
20
+ * memory: it changes every half second while its reply streams, but it is
21
+ * written only when it starts, when its response headers arrive and when it
22
+ * ends.
23
+ */
24
+ export class RequestStore {
25
+ db;
26
+ retentionDays;
27
+ /** Running calls by id, and whether the stored copy has the response. */
28
+ running = new Map();
29
+ constructor({ path = ':memory:', retentionDays = 7 } = {}) {
30
+ this.retentionDays = retentionDays;
31
+ this.db = new DatabaseSync(path);
32
+ // auto_vacuum only takes effect if set before the table is made.
33
+ // secure_delete overwrites what a delete frees, so cleared prompts
34
+ // don't stay in the file.
35
+ this.db.exec(`
36
+ PRAGMA auto_vacuum = INCREMENTAL;
37
+ PRAGMA journal_mode = WAL;
38
+ PRAGMA synchronous = NORMAL;
39
+ PRAGMA secure_delete = ON;
40
+ CREATE TABLE IF NOT EXISTS calls (
41
+ id TEXT PRIMARY KEY,
42
+ start INTEGER NOT NULL,
43
+ project TEXT NOT NULL,
44
+ ended INTEGER NOT NULL,
45
+ summary TEXT NOT NULL,
46
+ record TEXT NOT NULL
47
+ );
48
+ CREATE INDEX IF NOT EXISTS calls_project_start ON calls (project, start);
49
+ `);
50
+ this.markInterrupted();
51
+ }
52
+ /**
53
+ * Adds a call, or replaces the one with the same id: a call is handed over
54
+ * while it runs and again when it ends.
55
+ */
56
+ addRequest(captured) {
57
+ const ended = captured.timings.end !== undefined;
58
+ const known = this.running.get(captured.id);
59
+ const store = ended ||
60
+ !known ||
61
+ (captured.response !== undefined && !known.storedResponse);
62
+ if (store)
63
+ this.write(captured);
64
+ if (ended) {
65
+ this.running.delete(captured.id);
66
+ }
67
+ else {
68
+ this.running.set(captured.id, {
69
+ captured,
70
+ storedResponse: captured.response !== undefined ||
71
+ (known?.storedResponse ?? false),
72
+ });
73
+ }
74
+ }
75
+ /** Summaries, newest first, of the calls `query` keeps. */
76
+ summaries({ project, search = '', since, limit, ...filters } = {}) {
77
+ const pattern = likePattern(search);
78
+ // A running call's stored copy is behind, so it is checked in memory.
79
+ const rows = this.db
80
+ .prepare(`SELECT id, summary, CASE WHEN :search = '' THEN NULL ELSE record END AS record
81
+ FROM calls
82
+ WHERE (:project IS NULL OR project = :project)
83
+ AND (:since IS NULL OR start >= :since)
84
+ AND (:pattern IS NULL OR record LIKE :pattern ESCAPE '\\'
85
+ OR id IN (SELECT value FROM json_each(:running)))
86
+ ORDER BY start DESC, rowid DESC`)
87
+ .all({
88
+ search,
89
+ project: project ?? null,
90
+ since: since ?? null,
91
+ pattern,
92
+ running: JSON.stringify([...this.running.keys()]),
93
+ });
94
+ const summaries = [];
95
+ for (const row of rows) {
96
+ // Search and filters apply after the query, so the limit is counted here.
97
+ if (summaries.length === limit)
98
+ break;
99
+ const live = this.running.get(row.id)?.captured;
100
+ if (search) {
101
+ const captured = live ?? JSON.parse(row.record ?? '');
102
+ if (!matchesSearch(captured, search))
103
+ continue;
104
+ }
105
+ const summary = live
106
+ ? toSummary(live)
107
+ : JSON.parse(row.summary);
108
+ if (matchesFilters(summary, filters))
109
+ summaries.push(summary);
110
+ }
111
+ return summaries;
112
+ }
113
+ /** The calls `query` keeps (every call by default) in full, newest first. */
114
+ getRequests(query) {
115
+ return this.summaries(query).map(({ id }) => this.get(id));
116
+ }
117
+ get(id) {
118
+ const live = this.running.get(id);
119
+ if (live)
120
+ return live.captured;
121
+ const row = this.db
122
+ .prepare('SELECT record FROM calls WHERE id = ?')
123
+ .get(id);
124
+ return row && JSON.parse(row.record);
125
+ }
126
+ /** Removes the call with this id, and says whether there was one. */
127
+ remove(id) {
128
+ this.running.delete(id);
129
+ const { changes } = this.db
130
+ .prepare('DELETE FROM calls WHERE id = ?')
131
+ .run(id);
132
+ this.vacuum();
133
+ return changes > 0;
134
+ }
135
+ /** Removes every call of `project`, or every call when it is undefined. */
136
+ clear(project) {
137
+ for (const [id, { captured }] of this.running) {
138
+ if (project === undefined || captured.project === project) {
139
+ this.running.delete(id);
140
+ }
141
+ }
142
+ this.db
143
+ .prepare('DELETE FROM calls WHERE :project IS NULL OR project = :project')
144
+ .run({ project: project ?? null });
145
+ this.vacuum();
146
+ }
147
+ /** Removes ended calls that started more than `retentionDays` before `now`. */
148
+ prune(now = Date.now()) {
149
+ if (this.retentionDays === 0)
150
+ return;
151
+ const { changes } = this.db
152
+ .prepare('DELETE FROM calls WHERE ended = 1 AND start < ?')
153
+ .run(now - this.retentionDays * DAY_MS);
154
+ if (changes > 0)
155
+ this.vacuum();
156
+ }
157
+ close() {
158
+ this.db.close();
159
+ }
160
+ write(captured) {
161
+ this.db
162
+ .prepare(`INSERT INTO calls (id, start, project, ended, summary, record)
163
+ VALUES (?, ?, ?, ?, ?, ?)
164
+ ON CONFLICT (id) DO UPDATE SET
165
+ ended = excluded.ended, summary = excluded.summary, record = excluded.record`)
166
+ .run(captured.id, captured.timings.start, captured.project, captured.timings.end === undefined ? 0 : 1, JSON.stringify(toSummary(captured)), JSON.stringify(captured));
167
+ }
168
+ /**
169
+ * Calls left running by a LLMSpy that stopped: nothing will end them, so
170
+ * they end where their data stops, with an error that says so.
171
+ */
172
+ markInterrupted() {
173
+ const rows = this.db
174
+ .prepare('SELECT record FROM calls WHERE ended = 0')
175
+ .all();
176
+ for (const row of rows) {
177
+ const captured = JSON.parse(row.record);
178
+ const { start, firstByte, lastData } = captured.timings;
179
+ captured.timings.end = lastData ?? firstByte ?? start;
180
+ captured.error = INTERRUPTED;
181
+ this.write(captured);
182
+ }
183
+ }
184
+ /** Gives the pages a delete freed back to the file system. */
185
+ vacuum() {
186
+ this.db.exec('PRAGMA incremental_vacuum');
187
+ }
188
+ }
189
+ /**
190
+ * A `LIKE` pattern that finds `search` in a record's JSON, or null for no
191
+ * search. `LIKE` ignores case for ASCII only, so a search with other
192
+ * letters is left to `matchesSearch` alone.
193
+ */
194
+ function likePattern(search) {
195
+ const ascii = [...search].every((char) => char.charCodeAt(0) < 0x80);
196
+ if (!search || !ascii)
197
+ return null;
198
+ // The record is JSON, so the text is in it escaped as JSON escapes it.
199
+ const escaped = JSON.stringify(search).slice(1, -1);
200
+ return `%${escaped.replace(/[\\%_]/g, '\\$&')}%`;
201
+ }
@@ -0,0 +1,50 @@
1
+ import { isFailed } from './failed.js';
2
+ /** The fields of a record the list of calls shows. */
3
+ export function toSummary(captured) {
4
+ const { response, llm } = captured;
5
+ return {
6
+ id: captured.id,
7
+ timestamp: captured.timestamp,
8
+ project: captured.project,
9
+ provider: captured.provider,
10
+ host: captured.host,
11
+ method: captured.method,
12
+ path: captured.path,
13
+ response: response && { status: response.status },
14
+ timings: captured.timings,
15
+ latency: captured.latency,
16
+ error: captured.error,
17
+ llm: llm && { model: llm.model, usage: llm.usage, error: llm.error },
18
+ };
19
+ }
20
+ /** Whether a call's summary passes every filter given. */
21
+ export function matchesFilters(summary, { model, status, failed }) {
22
+ if (model !== undefined &&
23
+ !summary.llm?.model?.toLowerCase().includes(model.toLowerCase())) {
24
+ return false;
25
+ }
26
+ if (status !== undefined &&
27
+ !matchesStatus(summary.response?.status, status)) {
28
+ return false;
29
+ }
30
+ return !failed || isFailed(summary);
31
+ }
32
+ /** `429` matches that status only, `5xx` any status from 500 to 599. */
33
+ function matchesStatus(actual, wanted) {
34
+ if (actual === undefined)
35
+ return false;
36
+ const code = String(actual);
37
+ return wanted.endsWith('xx') ? code[0] === wanted[0] : code === wanted;
38
+ }
39
+ /** Case-insensitive match on host, path and both bodies; an empty search matches all. */
40
+ export function matchesSearch(captured, search) {
41
+ if (!search)
42
+ return true;
43
+ const term = search.toLowerCase();
44
+ return [
45
+ captured.host,
46
+ captured.path,
47
+ captured.body,
48
+ captured.response?.body ?? '',
49
+ ].some((field) => field.toLowerCase().includes(term));
50
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,85 @@
1
+ const DEFAULT_UPSTREAMS = {
2
+ anthropic: 'https://api.anthropic.com',
3
+ openai: 'https://api.openai.com',
4
+ };
5
+ /** First path segments that LLMSpy's own endpoints and the built UI use. */
6
+ const RESERVED_NAMES = new Set(['api', 'assets', 'events', 'ping']);
7
+ const NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
8
+ /**
9
+ * Builds the upstream map from the defaults plus `LLMSPY_UPSTREAMS`,
10
+ * a comma-separated list of `name=url` (e.g. `ollama=http://localhost:11434`).
11
+ * A name that matches a default replaces it.
12
+ */
13
+ export function parseUpstreams(spec) {
14
+ const upstreams = new Map();
15
+ for (const [name, url] of Object.entries(DEFAULT_UPSTREAMS)) {
16
+ upstreams.set(name, new URL(url));
17
+ }
18
+ for (const entry of (spec ?? '').split(',')) {
19
+ const trimmed = entry.trim();
20
+ if (!trimmed)
21
+ continue;
22
+ const eq = trimmed.indexOf('=');
23
+ if (eq < 1) {
24
+ throw new Error(`LLMSPY_UPSTREAMS: expected name=url, got "${trimmed}"`);
25
+ }
26
+ const name = trimmed.slice(0, eq).trim().toLowerCase();
27
+ const rawUrl = trimmed.slice(eq + 1).trim();
28
+ if (!NAME_PATTERN.test(name) || RESERVED_NAMES.has(name)) {
29
+ throw new Error(`LLMSPY_UPSTREAMS: "${name}" is not a usable name (lowercase letters, digits and dashes; not ${[...RESERVED_NAMES].join(', ')})`);
30
+ }
31
+ let url;
32
+ try {
33
+ url = new URL(rawUrl);
34
+ }
35
+ catch {
36
+ throw new Error(`LLMSPY_UPSTREAMS: "${rawUrl}" for ${name} is not a valid URL`);
37
+ }
38
+ if (url.protocol !== 'http:' && url.protocol !== 'https:') {
39
+ throw new Error(`LLMSPY_UPSTREAMS: ${name} must use http or https, got ${url.protocol}`);
40
+ }
41
+ upstreams.set(name, url);
42
+ }
43
+ return upstreams;
44
+ }
45
+ /**
46
+ * The upstreams as shown to the UI, in configuration order. Any user name
47
+ * or password in a target URL is left out, so it never reaches a browser.
48
+ */
49
+ export function listUpstreams(upstreams) {
50
+ return [...upstreams].map(([name, url]) => {
51
+ const target = new URL(url);
52
+ target.username = '';
53
+ target.password = '';
54
+ return { name, target: target.href };
55
+ });
56
+ }
57
+ /** The project of a call sent without `/@<project>` in front. */
58
+ const DEFAULT_PROJECT = 'general';
59
+ /** Whether `name` can be a project name: the same rule as upstream names. */
60
+ export function isProjectName(name) {
61
+ return NAME_PATTERN.test(name);
62
+ }
63
+ /**
64
+ * Maps `/<name>/rest?query` to the upstream `name`, appending `rest?query`
65
+ * to the upstream's base path. An optional `/@<project>` in front tags the
66
+ * call with a project and is not forwarded. Returns undefined when no
67
+ * upstream matches or the project name is not usable.
68
+ */
69
+ export function resolveRoute(requestUrl, upstreams) {
70
+ const match = /^(?:\/@([^/?]*))?\/([^/?]+)([^?]*)(\?.*)?$/.exec(requestUrl);
71
+ if (!match)
72
+ return undefined;
73
+ const [, project = DEFAULT_PROJECT, provider, rest, query] = match;
74
+ if (!isProjectName(project))
75
+ return undefined;
76
+ const base = upstreams.get(provider);
77
+ if (!base)
78
+ return undefined;
79
+ // Set the parts rather than resolving a relative URL, so a path such as
80
+ // `//other.host/x` stays a path on this upstream.
81
+ const target = new URL(base.origin);
82
+ target.pathname = base.pathname.replace(/\/$/, '') + (rest || '/');
83
+ target.search = query ?? '';
84
+ return { project, provider, target };
85
+ }
@@ -0,0 +1,14 @@
1
+ import { readFileSync } from 'node:fs';
2
+ import { fileURLToPath } from 'node:url';
3
+ // proxy/package.json, from src/ (tsx) and dist/ alike; the image and the npm
4
+ // package ship it too. A URL rather than import.meta.dirname, so that the CLI
5
+ // can load this module on an old Node and still say which version it needs.
6
+ const packageFile = fileURLToPath(new URL('../package.json', import.meta.url));
7
+ /** LLMSpy's version, from proxy/package.json. */
8
+ export function readVersion() {
9
+ const { version } = JSON.parse(readFileSync(packageFile, 'utf8'));
10
+ if (typeof version !== 'string') {
11
+ throw new Error(`No version in ${packageFile}`);
12
+ }
13
+ return version;
14
+ }
@@ -0,0 +1,6 @@
1
+ {
2
+ "name": "llmspy-proxy",
3
+ "version": "0.4.0",
4
+ "private": true,
5
+ "type": "module"
6
+ }