{"id":50883879,"url":"https://github.com/clearclown/liqueur","last_synced_at":"2026-06-15T15:01:27.790Z","repository":{"id":333319105,"uuid":"1132095026","full_name":"clearclown/liqueur","owner":"clearclown","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-18T15:21:11.000Z","size":22007,"stargazers_count":1,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T22:22:47.800Z","etag":null,"topics":["ai","anthropic","dashboard","deepseek","gemini","generative-ui","json-schema","llm","no-code","openai","react","rust","server-driven-ui","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/clearclown.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-11T10:13:27.000Z","updated_at":"2026-01-18T15:40:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/clearclown/liqueur","commit_stats":null,"previous_names":["clearclown/liqueur"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/clearclown/liqueur","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clearclown%2Fliqueur","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clearclown%2Fliqueur/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clearclown%2Fliqueur/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clearclown%2Fliqueur/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clearclown","download_url":"https://codeload.github.com/clearclown/liqueur/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clearclown%2Fliqueur/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34367696,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","anthropic","dashboard","deepseek","gemini","generative-ui","json-schema","llm","no-code","openai","react","rust","server-driven-ui","typescript"],"created_at":"2026-06-15T15:01:25.776Z","updated_at":"2026-06-15T15:01:27.763Z","avatar_url":"https://github.com/clearclown.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Liquid Protocol\n\n**Transform dashboards with natural language.**\n\nOpen-source protocol for AI-driven UI generation\n\n[![npm](https://img.shields.io/npm/v/@liqueur/protocol?style=flat-square\u0026color=blue)](https://www.npmjs.com/package/@liqueur/protocol)\n[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)\n\nEnglish | [日本語](./docs/readmeLangs/README.ja.md) | [简体中文](./docs/readmeLangs/README.zh-CN.md) | [繁體中文](./docs/readmeLangs/README.zh-TW.md) | [Русский](./docs/readmeLangs/README.ru.md) | [Українська](./docs/readmeLangs/README.uk.md) | [فارسی](./docs/readmeLangs/README.fa.md) | [العربية](./docs/readmeLangs/README.ar.md)\n\n\u003c/div\u003e\n\n---\n\n## In a Nutshell\n\n**\"Exclude transportation costs and show monthly expenses as a bar chart\"**\n\nJust say this, and your dashboard automatically reconfigures itself.\n\n\u003cdiv align=\"center\"\u003e\n\n| Before | After |\n|--------|-------|\n| ![Initial Dashboard](docs/images/dashboard-initial.png) | ![After AI Update](docs/images/dashboard-after-ai.png) |\n| Default dashboard | After saying \"Exclude transportation\" |\n\n\u003c/div\u003e\n\n---\n\n## Quick Start (30 seconds)\n\n```bash\nnpx create-next-liqueur-app my-dashboard\ncd my-dashboard\nnpm run dev\n```\n\nOpen [http://localhost:3000](http://localhost:3000) and start chatting.\n\n---\n\n## Table of Contents\n\n- [Why Liquid Protocol?](#why-liquid-protocol)\n- [Comparison with Claude Artifacts / Gemini Canvas](#comparison-with-claude-artifacts--gemini-canvas)\n- [Use Cases](#use-cases)\n- [How It Works](#how-it-works)\n- [Installation](#installation)\n- [Developer Setup](#developer-setup)\n- [Security Design](#security-design)\n- [Schema Specification](#schema-specification)\n- [Roadmap](#roadmap)\n\n---\n\n## Why Liquid Protocol?\n\n### The Customization Dilemma\n\nConsider a budget tracking app. No matter which app you use, you'll always have requests like:\n\n\u003e - \"Exclude transportation costs - my company reimburses those\"\n\u003e - \"Family card purchases should be separate - I get reimbursed\"\n\u003e - \"Tag all spending during my trip as 'travel'\"\n\u003e - \"I hate red - make it blue and black\"\n\n**Current solutions:**\n\n| Approach | Example | Problem |\n|:---------|:--------|:--------|\n| Build everything yourself | Notion, Spreadsheets | Customization becomes the goal. You lose focus |\n| Add more settings | Traditional apps | Settings screens become complex. \"Too much freedom\" |\n\n### Liquid's Solution\n\n**Just say what you want.**\n\n```\nUser: \"Exclude transportation costs\"\n    ↓\nAI regenerates the dashboard structure\n    ↓\nFilters, charts, and layouts update automatically\n```\n\nNo more hunting through settings screens.\n\n---\n\n## Comparison with Claude Artifacts / Gemini Canvas\n\nHave you used [Claude Artifacts](https://support.anthropic.com/en/articles/9487310-what-are-artifacts-and-how-do-i-use-them) or [Gemini Canvas](https://gemini.google/overview/canvas/)?\n\nThey're amazing features that let you generate dashboards and code through AI conversations.\n\n**Liquid Protocol brings this experience to YOUR app.**\n\n| Feature | Claude Artifacts | Gemini Canvas | **Liquid Protocol** |\n|---------|:---------------:|:-------------:|:-------------------:|\n| AI-powered UI generation | ✅ | ✅ | ✅ |\n| Embed in your own app | ❌ | ❌ | **✅** |\n| Connect your own database | ❌ | ❌ | **✅** |\n| Row-Level Security | ❌ | ❌ | **✅** |\n| Code execution risk | ⚠️ Sandboxed | ⚠️ Sandboxed | **✅ None** |\n| Open Source | ❌ | ❌ | **✅ MIT** |\n| AI provider choice | Claude only | Gemini only | **Any** |\n\n### In Summary\n\n```\nClaude Artifacts / Gemini Canvas\n  → Amazing. But only within THEIR apps.\n\nLiquid Protocol\n  → The same experience in YOUR app.\n    Your database, your users.\n```\n\n---\n\n## Use Cases\n\nWe're demonstrating with a budget app, but this technology applies to any application:\n\n| Application | Traditional Problem | Liquid Solution |\n|:------------|:-------------------|:----------------|\n| **Slack / Discord** | Complex notification settings | \"Only notify me for important conversations\" |\n| **Stock Trading** | Fixed dashboards | \"Show only tech stocks in a pie chart\" |\n| **Twitter / SNS** | Opaque algorithm | \"Hide political content\" |\n| **Project Management** | Jira settings hell | \"Show only my tasks this week\" |\n\n**This technology will become the software standard.**\n\n---\n\n## How It Works\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│  User: \"Exclude transportation, show as bar chart\"          │\n└─────────────────────────────────────────────────────────────┘\n                            ↓\n┌─────────────────────────────────────────────────────────────┐\n│  AI (Claude / GPT / Gemini / DeepSeek / GLM)                │\n│                                                             │\n│  ⚠️ Outputs JSON schema ONLY. No JS/SQL generation          │\n└─────────────────────────────────────────────────────────────┘\n                            ↓\n┌─────────────────────────────────────────────────────────────┐\n│  @liqueur/protocol                                          │\n│                                                             │\n│  ✅ Schema validation: Unknown fields rejected immediately  │\n│  ✅ TypeScript + Rust dual validation                       │\n└─────────────────────────────────────────────────────────────┘\n                            ↓\n┌─────────────────────────────────────────────────────────────┐\n│  @liqueur/db-adapter                                        │\n│                                                             │\n│  🔒 Row-Level Security                                      │\n│  🔒 SQL injection prevention                                │\n└─────────────────────────────────────────────────────────────┘\n                            ↓\n┌─────────────────────────────────────────────────────────────┐\n│  @liqueur/react                                             │\n│                                                             │\n│  📊 Auto-render charts, tables, and layouts                 │\n└─────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Installation\n\n### By Use Case\n\n```bash\n# Schema definitions only\nnpm install @liqueur/protocol\n\n# Add React UI\nnpm install @liqueur/protocol @liqueur/react\n\n# Full stack (AI + Database)\nnpm install @liqueur/protocol @liqueur/react @liqueur/ai-provider @liqueur/db-adapter\n```\n\n### Packages\n\n| Package | Purpose |\n|:--------|:--------|\n| [@liqueur/protocol](https://www.npmjs.com/package/@liqueur/protocol) | Schema types \u0026 validation |\n| [@liqueur/react](https://www.npmjs.com/package/@liqueur/react) | UI components |\n| [@liqueur/ai-provider](https://www.npmjs.com/package/@liqueur/ai-provider) | AI provider integration |\n| [@liqueur/db-adapter](https://www.npmjs.com/package/@liqueur/db-adapter) | Prisma query execution |\n| [@liqueur/artifact-store](https://www.npmjs.com/package/@liqueur/artifact-store) | Schema persistence |\n| [create-next-liqueur-app](https://www.npmjs.com/package/create-next-liqueur-app) | Project scaffolding CLI |\n\n---\n\n## Developer Setup\n\n### Option 1: Quick Start with CLI\n\n```bash\nnpx create-next-liqueur-app my-dashboard\ncd my-dashboard\n\n# Configure your AI provider\ncp .env.example .env\n# Edit .env with your API key\n\nnpm run dev\n```\n\n### Option 2: Add to Existing Project\n\n```bash\nnpm install @liqueur/protocol @liqueur/react @liqueur/ai-provider\n```\n\n### Environment Variables\n\nWhen using `@liqueur/ai-provider`, configure environment variables for your chosen AI provider:\n\n```bash\n# .env or .env.local\n\n# Choose provider: anthropic, openai, gemini, deepseek, glm, local\nAI_PROVIDER=anthropic\n\n# ─── Anthropic (Claude) ───────────────────────────────\nANTHROPIC_API_KEY=sk-ant-your-key\nANTHROPIC_MODEL=claude-3-5-haiku-20241022\n# Models: claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022, claude-3-opus-20240229\n\n# ─── OpenAI (GPT) ─────────────────────────────────────\nOPENAI_API_KEY=sk-your-key\nOPENAI_MODEL=gpt-4o-mini\n# Models: gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-3.5-turbo\n\n# ─── Google Gemini ────────────────────────────────────\nGOOGLE_API_KEY=your-key\nGEMINI_MODEL=gemini-1.5-flash\n# Models: gemini-2.0-flash-exp, gemini-1.5-pro, gemini-1.5-flash\n\n# ─── DeepSeek ─────────────────────────────────────────\nDEEPSEEK_API_KEY=sk-your-key\nDEEPSEEK_MODEL=deepseek-chat\n# Models: deepseek-chat, deepseek-coder\n\n# ─── GLM (Zhipu AI) ───────────────────────────────────\nGLM_API_KEY=your-key\nGLM_MODEL=glm-4\n# Models: glm-4, glm-4-flash, glm-3-turbo\n\n# ─── Local LLM (Ollama, LM Studio) ────────────────────\nLOCAL_LLM_BASE_URL=http://localhost:1234/v1\nLOCAL_LLM_MODEL=llama3\n```\n\n### Basic Usage\n\n```typescript\nimport { ProviderFactory } from '@liqueur/ai-provider';\nimport { LiquidRenderer } from '@liqueur/react';\n\n// Create provider from environment variables\nconst provider = ProviderFactory.createFromEnv();\n\n// Generate schema from natural language\nconst schema = await provider.generateSchema(\n  \"Show monthly expenses as a bar chart\",\n  databaseMetadata\n);\n\n// Render the dashboard\n\u003cLiquidRenderer schema={schema} data={data} /\u003e\n```\n\n### Example: Next.js API Route\n\n```typescript\n// app/api/generate/route.ts\nimport { NextRequest, NextResponse } from 'next/server';\nimport { ProviderFactory } from '@liqueur/ai-provider';\n\nexport async function POST(request: NextRequest) {\n  const { prompt } = await request.json();\n\n  const provider = ProviderFactory.createFromEnv();\n  const schema = await provider.generateSchema(prompt, metadata);\n\n  return NextResponse.json({ schema });\n}\n```\n\n### Sample Applications\n\n| Sample | Description | Run |\n|:-------|:------------|:----|\n| [Household Budget](./examples/household-budget) | Full-featured with AI chat | `cd examples/household-budget \u0026\u0026 pnpm dev` |\n| [Playground](./examples/playground) | Simple test environment | `cd examples/playground \u0026\u0026 pnpm dev` |\n\n### Run from Source\n\n```bash\ngit clone https://github.com/clearclown/liqueur.git\ncd liqueur\npnpm install \u0026\u0026 pnpm build\n\ncd examples/household-budget\ncp .env.example .env  # Configure API keys\npnpm dev\n```\n\n---\n\n## Security Design\n\n### Why Not Let AI Write JavaScript?\n\n| Approach | Risk |\n|:---------|:-----|\n| AI generates JS/SQL | XSS, SQL injection, arbitrary code execution |\n| **Liquid: JSON only** | No executable code. Unknown fields rejected |\n\n### Three Layers of Defense\n\n1. **AI Output Restriction** — JSON schema only. No code generation\n2. **Schema Validation** — Unknown fields rejected immediately (Fail Fast)\n3. **Row-Level Security** — Users can only access their own data\n\n```\n❌ What AI DOES NOT generate\n   - JavaScript\n   - SQL\n   - Shell commands\n\n✅ What AI generates\n   - Validated JSON schema only\n```\n\n---\n\n## Schema Specification\n\n### Basic Structure\n\n```typescript\ninterface LiquidViewSchema {\n  version: '1.0';\n  layout: Layout;\n  components: Component[];\n  data_sources: Record\u003cstring, DataSource\u003e;\n}\n```\n\n### Components\n\n- `chart` — Bar, line, pie, area charts\n- `table` — Data table (sortable)\n\n### DataSource\n\n```typescript\ninterface DataSource {\n  resource: string;      // Table name\n  filters?: Filter[];    // WHERE conditions\n  aggregation?: {        // GROUP BY + aggregation\n    type: 'sum' | 'count' | 'avg' | 'min' | 'max';\n    field: string;\n    by: string;\n  };\n  sort?: { field: string; direction: 'asc' | 'desc' };\n  limit?: number;\n}\n```\n\n### Example: Expenses excluding transportation\n\n```typescript\nconst schema: LiquidViewSchema = {\n  version: '1.0',\n  layout: { type: 'grid', columns: 2 },\n  components: [\n    {\n      type: 'chart',\n      variant: 'pie',\n      title: 'Monthly Expenses',\n      data_source: 'expenses'\n    }\n  ],\n  data_sources: {\n    expenses: {\n      resource: 'transactions',\n      filters: [\n        { field: 'type', op: 'eq', value: 'EXPENSE' },\n        { field: 'category', op: 'neq', value: 'Transportation' }  // ← Excluded\n      ],\n      aggregation: { type: 'sum', field: 'amount', by: 'category' }\n    }\n  }\n};\n```\n\nSee [@liqueur/protocol](./packages/protocol) for details.\n\n---\n\n## Roadmap\n\n- [x] Phase 1: Core protocol \u0026 React components\n- [x] Phase 2: AI provider integration\n- [x] Phase 3: Sample app (household budget)\n- [ ] Phase 4: Additional components (calendar, map, etc.)\n- [ ] Phase 5: Real-time collaborative editing\n- [ ] Phase 6: Plugin system\n\n---\n\n## Development\n\n```bash\npnpm install\npnpm build\npnpm test\n```\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for details.\n\n---\n\n## License\n\n[MIT](LICENSE)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Liquid Protocol**\n\nEnd the era of users fighting with settings\n\n[GitHub](https://github.com/clearclown/liqueur) · [npm](https://www.npmjs.com/package/@liqueur/protocol)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclearclown%2Fliqueur","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclearclown%2Fliqueur","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclearclown%2Fliqueur/lists"}