{"id":21311345,"url":"https://github.com/kickstartds/concierge","last_synced_at":"2025-07-11T23:32:28.123Z","repository":{"id":160130693,"uuid":"611931746","full_name":"kickstartDS/concierge","owner":"kickstartDS","description":"A ML based chat agent to answer Design System related questions","archived":false,"fork":false,"pushed_at":"2024-09-12T15:14:45.000Z","size":41259,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-11T05:39:47.924Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kickstartDS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-09T20:55:49.000Z","updated_at":"2024-11-19T10:22:16.000Z","dependencies_parsed_at":"2024-09-13T02:05:47.335Z","dependency_job_id":"d5b4f8e4-3853-4f2b-8291-3415f12230b7","html_url":"https://github.com/kickstartDS/concierge","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":"github/codespaces-jupyter","purl":"pkg:github/kickstartDS/concierge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kickstartDS%2Fconcierge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kickstartDS%2Fconcierge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kickstartDS%2Fconcierge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kickstartDS%2Fconcierge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kickstartDS","download_url":"https://codeload.github.com/kickstartDS/concierge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kickstartDS%2Fconcierge/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264913892,"owners_count":23682733,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-11-21T17:17:38.499Z","updated_at":"2025-07-11T23:32:25.061Z","avatar_url":"https://github.com/kickstartDS.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.kickstartDS.com/\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://www.kickstartds.com/docs/img/logo-light.svg\"\u003e\n      \u003cimg src=\"https://www.kickstartDS.com/logo.svg\" alt=\"kickstartDS\" width=\"400\" /\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n# kickstartDS Concierge - Your AI-powered Design System assistant\n\nThis repository contains all code related to the kickstartDS Concierge hosted at https://www.kickstartDS.com/concierge/\n\nRead more about its release on our blog post:  \nhttps://www.kickstartDS.com/blog/launching-the-design-system-concierge/\n\nFor a more detailed overview of the architecture, design decisions and some code... have a look at the following Miro board:  \nhttps://miro.com/app/board/uXjVMdpB0ao=/\n\n![Screenshot of the Design System Concierge](assets/screenshot-concierge.png)\n\nThe Concierge can answer user questions by pulling from a big Design System-related knowledge base, gained by scraping manually curated domains on the web.\n\nCrawled HTML gets processed, sections of content are split from it along headline elements, and some metadata is enriched. Finally those sections get transformed to an embedding vector space that is saved to a PostgreSQL database using the `pgvector` extension.\n\nRequests from the page are sent to a Supabase Edge Function, which get's an embedding for the question by calling the Flask webservice contained within this repository. This embedding is then sent to the database to get back the most relevant sections in relation to the question. This then, finally, gets embedded as context into a GPT Completion prompt, which generates the final answer being streamed back to the user. Additionally links and a preview to all referenced pages gets included as context.\n\n## Flask webservice\n\n### Run locally\n\nRun app first:\n\n```\nFLASK_APP=app flask run\n```\n\nNow send questions to the locally running service:\n\n```\ncurl -d '{\"question\": \"What is a Design System?\"}' -H \"Content-Type: application/json\" -X POST http://127.0.0.1:5000\n```\n\n### Run on Fly.io\n\nInstall `flyctl` first. E.g. Arch Linux:\n\n```\ntrizen -S flyctl-bin\n```\n\nLog in to your account with `flyctl`:\n\n```\nflyctl auth login\n```\n\nDeploy a version:\n\n```\nflyctl deploy\n```\n\nQuery the running webservice:\n\n```\ncurl -d '{\"question\": \"What is a Design System?\"}' -H \"Content-Type: application/json\" -X POST https://question-embedding.fly.dev\n```\n\n## Database\n\nThis project uses PostgreSQL for data storage, and `pgvector` as an extension specifically:  \nhttps://github.com/pgvector/pgvector\n\n### Installation\n\nNeeded tables are generated by `notebooks/create_knowledge_base.ipynb` when `seed = True` is set in cell \"Write embeddings to DB\".\n\nBut you'll need the following `pgsql` database function:\n\n```pgsql\ndrop function match_sections (\n  query_embedding vector(768),\n  similarity_threshold float,\n  match_count int\n);\ncreate or replace function match_sections (\n  query_embedding vector(768),\n  similarity_threshold float,\n  match_count int\n)\nreturns table (\n  id bigint,\n  tokens integer,\n  content text,\n  page_url text,\n  page_title text,\n  page_summary text,\n  similarity float\n)\nlanguage plpgsql\nas $$\nbegin\n  return query\n  select\n    sections.id,\n    sections.tokens,\n    sections.content,\n    sections.page_url,\n    sections.page_title,\n    sections.page_summary,\n    1 - (sections.embedding \u003c=\u003e query_embedding) as similarity\n  from sections\n  where 1 - (sections.embedding \u003c=\u003e query_embedding) \u003e similarity_threshold\n  order by sections.embedding \u003c=\u003e query_embedding\n  limit match_count;\nend;\n$$;\n```\n\n### Supabase\n\nYou will need an account with Supabase to use this repository for yourself directly. But it should be easily adaptable to other hosters, too!\n\n#### Create database function\n\n1. Go to the \"SQL editor\" section.\n2. Click \"New Query\".\n3. Enter the above SQL to create or replace your Database function.\n4. Click \"Run\" or cmd+enter (ctrl+enter).\n\nSee also: https://supabase.com/docs/guides/database/functions\n\n#### Create edge function\n\n1. Install Supabase CLI: https://supabase.com/docs/guides/cli\n2. Deploy edge function: `yarn supabase functions deploy answer`\n\nOptionally integrate the Deno language server with your editor for autocompletion, etc:  \nhttps://deno.land/manual/getting_started/setup_your_environment\n\nSee also: https://supabase.com/docs/guides/functions/quickstart\n\n#### Create database types\n\n```\nyarn supabase gen types typescript --db-url postgres://postgres:YOUR_POSTGRES_PASS@YOUR_POSTGRES_URL:5432/postgres \u003e dbTypes.ts\n```\n\n## Contributing\n\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in the work by you, as defined in the Apache-2.0 license, shall be\ndual licensed as below, without any additional terms or conditions.\n\n## License\n\n\u0026copy; Copyright 2023 Jonas Ulrich, kickstartDS by ruhmesmeile GmbH [jonas.ulrich@kickstartds.com].\n\nThis project is licensed under either of\n\n- [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0) ([`LICENSE-APACHE`](LICENSE-APACHE))\n- [MIT license](https://opensource.org/licenses/MIT) ([`LICENSE-MIT`](LICENSE-MIT))\n\nat your option.\n\nThe [SPDX](https://spdx.dev) license identifier for this project is `MIT OR Apache-2.0`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkickstartds%2Fconcierge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkickstartds%2Fconcierge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkickstartds%2Fconcierge/lists"}