Repository navigation
Releases
v0.4.0
The release that turns a prompt library into Lapidary: an agent harness, a Windows console made for people who do not know AI yet, local models and a model policy, memory, and gates. Everything below merged between 2026-10-25 and 2026-10-26 (pull requests 36 to 52).
Added
- Agent harness (ADR-007, roadmap items 13, 32 to 34). A gem has a
kind(promptoragent) and a list oftools;backend/app/agents/holds a tool registry (@toolfunctions with a JSON schema from the signature, risky or not), a provider-neutral run loop with a step cap, and a run store (runs,run_events). Surfaces:POST /agents/{name}/runs(JSON or SSE),GET /runs/{id},GET /agents/tools, the MCP toolsrun_agent,approve_runandlist_agent_tools, theruns://{id}resource. Approval gates with pause and resume: a risky tool call pauses the run (waiting_approval, loop state inruns.state),POST /runs/{id}/approvecontinues it. Tools from other MCP servers throughconfigs/mcp_servers.json(<server>.<tool>,<server>.*, risky unless the entry says otherwise). Built-in toolssearch_gems,get_gem,resolve_gemandrun_powershell(risky). The web UI streams prompt gems token by token, runs agent gems with live events, replays any run at/runs/{id}, and the editor has a kind select and a tool picker. Seed agentsgem_librarian,rea_analyst(for the REA tools) andwindows_operator. - OpenAI-compatible API (roadmap item 36).
GET /v1/modelsandPOST /v1/chat/completionswith bearer auth on the same key, so Open WebUI and any OpenAI client see every gem as a model; agent gems stream their tool activity as status lines before the answer. - Lapidary Console (ADR-009, ADR-012, roadmap items 36 to 40, 47 to 50). A Windows 11 Electron application in
desktop/that installs, connects and manages the AI tools on a machine with Lapidary as the hub: detection and installs through winget, Docker and npm (PowerShell 7, Node, Docker Desktop, Claude Desktop, ChatGPT, Ollama, Open WebUI, REA); config writers that register Lapidary and REA in Claude Desktop and ChatGPT and start Open WebUI with Lapidary, OpenAI and Ollama as providers; keys in the operating system's credential store; the backend and the UI as sidecars; a PowerShell 7 view; a toolbox of seventeen Windows management tools installed from their publishers. Retro terminal design. A guided first run: Basic asks "Which AI should we use?" and "What would you like?" and runs one of eight recipes (a private chat on this PC, homework and writing help, ask my documents, a research assistant, build me a program, my prompts in Claude and ChatGPT, a safe PowerShell assistant, understand an app) with progress and "here is what you can do now"; Advanced walks a system administrator through every choice and shows every file before it is written; an Advanced switch reveals the details on every screen. The Doctor checks everything the console can see and offers one-click fixes. Every view and component explains what it is for and what it costs or needs. The Windows installer is built and smoke-tested in CI (.github/workflows/desktop.yml). - Storage layer (roadmap item 38).
backend/app/storage/with oneStoreinterface and two backends: SQLite (one file, seeded on first use from theINSERTinsupabase/schema.sql) and Supabase. Chosen byGEMS_STORAGE, SQLite unlessSUPABASE_URLis set. - Local models and the model policy (ADR-011, roadmap item 44).
localis a third provider: any OpenAI-compatible server atLOCAL_OPENAI_BASE_URL(Ollama by default, LM Studio, oMLX, vLLM).GEMS_MODEL_POLICYanswers "Which AI should we use?":local,online,mix,auto(the default) ormanual;backend/app/services/router.pydecides per call from the policy, the gem's role and what is available, with fallback and a plain-words reason returned in chat responses, run events and the MCP tool.GET /chat/policydescribes the world for the UI. New gems default toauto. - Lapidary Memory (ADR-010, roadmap item 43). A
memoriestable in both stores with full-text search (FTS5 on SQLite,tsvectoron Supabase) holding observations, summaries, decisions, preferences, lessons, handoffs and notes with a source, tags and a scope. When a run finishes an observation is stored, written by thememory_summarizergem when a model is available and as a plain digest otherwise; text inside<private>...</private>is never stored. Recall in three steps:search_memory,get_memories,rememberandforgetas built-in agent tools, MCP tools and routes under/memory; a gem withmemory: truegets the top matches inside a<memory>block before its prompt. A Memory page in the web UI. SettingsGEMS_MEMORY_CAPTURE,GEMS_MEMORY_SUMMARIZE,GEMS_MEMORY_RECALL_LIMIT,GEMS_MEMORY_RECALL_MAX_CHARS,GEMS_MEMORY_MAX_CHARS. - Pipelines and gates (ADR-011, roadmap item 45). A pipeline is a builder gem followed by gate gems with roles (test, visual, review, custom), an attempt cap and an acceptance step; each gate ends with
VERDICT: PASSorVERDICT: FAIL, a fail becomes feedback for the next attempt and a memory lesson, every attempt and gate is an ordinary run, a risky call pauses the pipeline, and a pass through every gate waits for a person to accept. Tablespipelinesandpipeline_runs, routes under/pipelines, MCP toolslist_pipelines,run_pipeline,resume_pipeline, the gate gemstest_runnerandadversarial_reviewer, the seed pipelinebuild_and_check, a Pipelines page with a run page. - Seed gems.
study_buddy,writing_coach,research_assistant,program_builder,memory_summarizer,test_runner,adversarial_reviewer,rea_analyst,windows_operator,gem_librarian, each also inprompts/. One-off Supabase migrations for existing installs:add_agent_runs.sql,add_rea_analyst.sql,add_windows_operator.sql,add_local_provider.sql,add_newcomer_gems.sql,add_memory.sql,add_pipelines.sql. - Settings
AGENT_MAX_STEPS,AGENT_TOOL_RESULT_MAX_CHARS,POWERSHELL_TIMEOUT_SECONDS,POWERSHELL_MAX_OUTPUT_CHARS,GEMS_MCP_SERVERS_FILE,GEMS_MCP_TOOLS_TTL_SECONDS,GEMS_MCP_CALL_TIMEOUT_SECONDS,GEMS_STORAGE,GEMS_SQLITE_PATH,GEMS_SEED_SQL_FILE,LOCAL_OPENAI_BASE_URL,LOCAL_OPENAI_API_KEY,GEMS_LOCAL_DEFAULT_MODEL,GEMS_MODEL_POLICY,GEMS_CLOUD_DEFAULT_PROVIDER,GEMS_CLOUD_DEFAULT_MODEL,GEMS_MODELS_LOCAL.
Changed
- The project is now called Lapidary (ADR-008). README, docs, the API title and root endpoint, the MCP server name (
lapidary), the web UI branding and the frontend package name use it; the repository ispoyfather/lapidary(old URLs redirect). TheGEMS_*environment variables and the word gem are unchanged. - Plain language on screen (ADR-012, roadmap item 48). In the web UI a gem is a prompt, an agent is an assistant, variables are blanks to fill, the resolved prompt is "the prompt as sent", a run is "what the assistant did", the provider is "which AI", and every error says what to do next (
frontend/lib/words.ts). The console says connect instead of MCP and keeps acronyms, file names and flags behind the Advanced switch. The API, the URLs and the developer docs keep the original words. - Run events
run_startedandrun_finishedcarry the run id;run_startedrecords which model answered and why. - New decision records ADR-007 to ADR-012 in
DECISIONS.md;ARCHITECTURE.mdanddocs/ROADMAP.mdcover the harness, the console, memory and gates (items 32 to 50).
Fixed
- The Windows installer's one-file backend did not start:
backend/run.pyhanded uvicorn the app as a string, so PyInstaller leftapp.mainand the routes out of the exe. The entry imports the app by name, the build collects uvicorn's submodules, and the smoke test lists the seed gems and prints the exe's output when it fails. - The web UI could not list prompts behind the Next.js proxy:
/api/gems/lost its trailing slash in the rewrite, the backend redirected to its own origin, and the browser followed without the key (a 401 on every library load).next.config.mjskeeps the slash. - The editor and the detail page showed
{{gem:name}}references with their first letter missing.
Security
- Private text is stripped from memories with a linear scan instead of a regular expression that CodeQL flagged as polynomial on user text (py/polynomial-redos).
v0.3.0
The first tagged release since v0.0.2 and the first one cut with the release workflow. It also restarts the version sequence: the 0.1.0 and 0.2.0 sections below predate the v0.0.2 tag, and nothing after that was tagged, so this release takes the next minor above the highest number in this file.
Security
- ADR-006: single-tenant access model. The
allow_allrow level security policy is dropped fromsupabase/schema.sqland RLS has no policies for theanonorauthenticatedroles, so only the service role key used by the backend and the MCP server can read or write gems.backend/app/database.pyaccepts the service role key only; the anon key option is removed from.env.example. Existing installs runsupabase/lock_down_rls.sqlonce (roadmap item 9). backend/app/services/gem_service.py: the{{gem:name}}pattern only matches identifier characters, so an unclosed tag can no longer make the resolver backtrack polynomially (CodeQL py/polynomial-redos). Regression tests added.backend/app/routes/chat.py: provider exceptions are logged server side and the client gets a generic 502 message, on both the JSON and the SSE path (CodeQL py/stack-trace-exposure).
Added
tests/conftest.pywith an in-memory stand-in for the gems table,tests/test_resolver.py(nesting, variable propagation, cycles, depth limit, braces in prompts) andtests/test_routes.py(auth, lookups, 404s, resolve) through FastAPI's TestClient;pytest.inisetspythonpathso the tests no longer patchsys.path(roadmap item 5). 29 tests.LICENSE(MIT),CONTRIBUTING.md,CODE_OF_CONDUCT.md(Contributor Covenant 2.1),SUPPORT.md..github/: issue forms (bug report, feature request, gem proposal) withconfig.yml, a pull request template,CODEOWNERS, Dependabot for pip, npm, Docker and Actions.- GitHub Actions:
ci.yml(ruff, pytest, import check,next lint,tsc,next build, prompts and schema sync, dash check),codeql.yml, andrelease.ymlwhich turns av*tag into a GitHub release from this file. ruff.tomlwith an explicit rule set,frontend/.eslintrc.json,frontend/package-lock.jsonsonpm ciworks..gitattributeswith line-ending rules andexport-ignorefor repo housekeeping files.docs/ROADMAP.md: prioritised roadmap of correctness, security, API, DX and release improvements.
Changed
backend/app/settings.pyis the one home for runtime defaults:GEMS_DEFAULT_PROVIDERandGEMS_DEFAULT_MODEL(nowclaude-opus-5-5) for new gems over REST, UI and MCP;LLM_TIMEOUT_SECONDS,LLM_MAX_RETRIESandLLM_MAX_TOKENSfor provider calls (roadmap items 17 and 18).GET /chat/modelsand the MCPlist_available_modelstool return each provider's live model list (OpenAI's filtered to chat models), cached forGEMS_MODEL_LIST_TTL_SECONDS, withGEMS_MODELS_ANTHROPICandGEMS_MODELS_OPENAIas pins and a static fallback. The static list with retiredclaude-3-5-*andgpt-3.5-turboentries is gone, and so are the hard-coded lists inGemForm.tsx.- Both SDK clients are built with an explicit timeout and retry count; any SDK failure becomes one
ProviderError, logged server side. - Seed gems and the eval use the new default model;
supabase/update_default_models.sqlmoves existing gems off retired models. - Frontend on Tailwind CSS 4 (
@tailwindcss/postcss), migrated with the official upgrade tool: thegem-*colours and the mono font stack live in an@themeblock inapp/globals.css,tailwind.config.tsandautoprefixerare gone, and the renamed utilities (outline-nonetooutline-hidden,roundedtorounded-sm) are updated in six files. Clears thepostcss-selector-parseradvisory that Dependabot PR 28 could only fix this way. - Frontend on Next.js 16.4.3 with React 19.3,
eslint9 and a flateslint.config.mjs(next lintis gone in Next 16, sonpm run lintrunseslint .),tsconfig.jsonas Next 16 requires it (jsx: react-jsx,target: ES2017), andfrontend/middleware.tsrenamed tofrontend/proxy.tsby the official codemod. The gems list page loads without a synchronous state update inside its effect, which the React 19 lint rules flag (roadmap item 7). - README "Why" rewritten in plain language: the problem (instructions scattered across tools), the drawer analogy, the two tricks (prompts inside prompts, blanks), and who it is and is not for yet.
docs/ROADMAP.md: four product items for prompt practitioners (28 evals per gem from the UI, 29 typed variables, 30 side-by-side runs, 31 few-shot examples as data), a closing "For the prompt practitioner" order of payoff, and stronger reasoning on 14, 21 and 22.- Frontend lint runs the strict
next/typescriptrule set:catch (e: any)is gone in favour of anerrorMessage()helper inlib/api.ts, unused imports inGemForm.tsxremoved, quotes in JSX escaped, and the chat page effect lists its dependency (roadmap item 8). ARCHITECTURE.mdrewritten around nine Mermaid diagrams (big picture, component model, two request sequences, gem composition, resolution walkthrough, data model, trust boundaries, deployment topologies) with a component table; the ASCII box drawing is gone. The big-picture diagram also sits in the README under "How it fits together".- README rewritten: one-line pitch, badges, three-step quick start, MCP client config with the real Claude Desktop config path, env var table, project layout.
SECURITY.mdnow opens with supported versions, how to report privately and the response window; the deployment policy follows.frontend/next.config.tsis nowfrontend/next.config.mjs. Next.js 14 does not load a TypeScript config, sonext dev,next lintandnext buildall failed before.- Backend: fastapi 0.156.4, uvicorn 0.54.0, supabase 2.33.0, anthropic 1.17.0, openai 3.35.1, fastmcp 4.1.3, pydantic 2.14.1, python-dotenv 1.2.4, python-multipart 0.0.32. Verified with the unit tests, the import check and the MCP tool registry on fastmcp 4.
- Frontend: next and eslint-config-next 14.2.35 (security patch), lucide-react 0.577.0. Next 15 and 16, React 19, Tailwind 4, ESLint 9 and 10 and TypeScript 7 are migrations tracked in
docs/ROADMAP.mditem 7 and are ignored by Dependabot until then. - Node 24 in CI and in
frontend/Dockerfile(Node 20 reached end of life in April 2026). Actions: checkout v7, setup-python v7, setup-node v7, codeql-action v4. .github/dependabot.yml: one pip entry at the root (it already scannedbackend/), grouped monthly PRs per ecosystem, and major versions ignored for the frontend toolchain and the Node image.
Fixed
- Docker Compose builds and runs:
next.config.mjssetsoutput: "standalone"andfrontend/public/exists, sofrontend/Dockerfilecan copy what it expects; the frontend container receivesGEMS_API_KEYandBACKEND_URL(and nothing else) and starts only after the backend's/healthpasses; the backend service no longer bind-mounts source or runs--reload;.dockerignorefiles keepnode_modules,.nextand.venvout of the build contexts; the obsoleteversionkey is gone. CI builds both images (roadmap item 1). GET,PUTandDELETE /gems/{id}accept a name or a UUID; an unknown value that is not a UUID is a 404 instead of a Postgres error surfacing as a 500 (roadmap item 2).POST /gems/resolvereportsvariables_usedas the placeholders that were actually present and filled, not the keys that were sent; the MCPresolve_gem_prompttool returns the same field (roadmap item 3).- Variables are filled in a single pass after expansion, so a value containing
{other}is never substituted again and the result no longer depends on dict order (roadmap item 3). - Only identifier-shaped
{name}placeholders are variables; JSON and code braces in a prompt no longer produce bogus variables or form fields (roadmap item 4). - The API key check uses
secrets.compare_digest(roadmap item 6). backend/requirements.txtcould not be installed:supabase==2.9.1requireshttpx<0.28whilefastmcp==2.2.0requireshttpx>=0.28.1. Nowsupabase==2.16.0andhttpx==0.28.1.frontend/app/chat/page.tsxwrapsuseSearchParams()in a Suspense boundary, whichnext buildrequires to prerender the page.- Lint: an unused import in
evals/eval_prompt_enhancer.py, a shadowedcreate_gemimport inbackend/mcp_server.py, and a combined import line intests/test_gem_service.py.
v0.0.2 — API Key Authentication
What's new
This release secures the backend with API key authentication end-to-end — both the FastAPI layer and the Next.js frontend proxy.
Added
backend/app/auth.py— FastAPISecuritydependency that validates anX-API-Keyrequest header againstGEMS_API_KEYin your environment. Returns HTTP 401 with a clear message on missing or invalid keys.frontend/middleware.ts— Next.js server-side middleware that injectsX-API-Keyon every/api/*request before the rewrite forwards it to FastAPI. The key is read from a server-only env var and never reaches the browser bundle.
Changed
- All
/gemsand/chatroutes are now protected via router-leveldependencies=[Depends(require_api_key)]— new endpoints are automatically covered. - Server startup validates
GEMS_API_KEYis present via FastAPI lifespan — misconfiguration is caught at boot, not on the first request. .env.exampleandfrontend/.env.local.exampleupdated withGEMS_API_KEYfield and a one-liner to generate a secure key.
Setup
Add the same key to both env files:
# Generate a key
python -c "import secrets; print(secrets.token_urlsafe(32))"
# backend/.env
GEMS_API_KEY=<your-generated-key>
# frontend/.env.local
GEMS_API_KEY=<your-generated-key>Restart both services. Unauthenticated API requests now return 401.