{"id":26140727,"url":"https://github.com/dpguthrie/dbt-semantic-layer-voice-agent","last_synced_at":"2025-10-07T07:55:55.988Z","repository":{"id":278414070,"uuid":"935542315","full_name":"dpguthrie/dbt-semantic-layer-voice-agent","owner":"dpguthrie","description":"Talk to your data!","archived":false,"fork":false,"pushed_at":"2025-06-20T22:44:25.000Z","size":1406,"stargazers_count":9,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-26T07:44:31.774Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","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/dpguthrie.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null}},"created_at":"2025-02-19T16:04:34.000Z","updated_at":"2025-07-17T12:12:49.000Z","dependencies_parsed_at":"2025-05-19T22:35:18.463Z","dependency_job_id":"17e78f33-ea54-4daf-afbf-64ec8183bf94","html_url":"https://github.com/dpguthrie/dbt-semantic-layer-voice-agent","commit_stats":null,"previous_names":["dpguthrie/dbt-semantic-layer-voice-agent"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dpguthrie/dbt-semantic-layer-voice-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpguthrie%2Fdbt-semantic-layer-voice-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpguthrie%2Fdbt-semantic-layer-voice-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpguthrie%2Fdbt-semantic-layer-voice-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpguthrie%2Fdbt-semantic-layer-voice-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dpguthrie","download_url":"https://codeload.github.com/dpguthrie/dbt-semantic-layer-voice-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpguthrie%2Fdbt-semantic-layer-voice-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278740823,"owners_count":26037480,"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","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"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":[],"created_at":"2025-03-11T02:56:21.784Z","updated_at":"2025-10-07T07:55:55.970Z","avatar_url":"https://github.com/dpguthrie.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Semantic Layer Assistant\n\nA real-time voice and text interaction application that helps users analyze data using a semantic layer. This application enables natural language queries to explore metrics and dimensions, with support for both voice and text-based interactions.\n\nhttps://www.loom.com/share/4804ce177dc24543858e4c5dfcd5600d?sid=b673ec1c-1c7d-4e6a-9d69-74ba4f5c49b5\n\n## Features\n\n- Natural language querying of semantic layer metrics and dimensions\n- Real-time voice input processing using OpenAI's Real-time Voice API\n- WebSocket-based real-time communication\n- Vector store-based semantic search for metrics and dimensions\n- Interactive data visualization with charts\n- Conversation persistence and management\n- Contextual querying with conversation-level filters and preferences\n- Data refresh capabilities for real-time updates\n\n## Architecture\n\nThe application consists of:\n- `server/`: Python backend using Starlette, LangChain, and dbt Semantic Layer\n- Vector store for efficient metric and dimension discovery\n- WebSocket-based real-time communication layer\n- Chart visualization using Chart.js\n- SQLite-based conversation and message storage\n\n![Application Architecture](assets/diagram.png)\n\n## Prerequisites\n\n- Python 3.12+\n- OpenAI API key with access to voice models\n- dbt semantic layer environment and credentials\n\n## Setup\n\n1. Copy the `.env.example` file to `.env` in the server directory and update with your credentials:\n\n```bash\ncp .env.example .env\n```\n\nThe `.env` file should contain:\n\n```bash\nOPENAI_API_KEY=your_api_key_here\nSL__HOST=your_semantic_layer_host\nSL__ENVIRONMENT_ID=your_environment_id\nSL__TOKEN=your_semantic_layer_token\n```\n\n2. [Optional] Install dependencies:\n\nCreate a virtual environment:\n\n```\nuv venv\n```\n\nInclude the development dependencies:\n```\nuv sync --all-extras\n```\n\nOr, install the dependencies without the development dependencies:\n\n```\nuv sync\n```\n\n## Running the Application\n\n1. Start the backend server:\n```bash\nuv run src/server/app.py\n```\n\n2. Open your browser to `http://localhost:3000`\n\n## Development\n\n### Backend Components\n\nThe backend is built using:\n- Starlette for the web server\n- LangChain for AI agent and tool execution\n- dbt Semantic Layer for data access\n- Pinecone for vector storage\n- WebSockets for real-time communication\n- SQLite for conversation storage\n\nKey files:\n- `server/src/langchain_openai_voice/__init__.py`: Core voice agent implementation\n- `server/src/server/app.py`: Starlette server implementation\n- `server/src/server/tools.py`: Semantic layer tool implementations\n- `server/src/server/vectorstore.py`: Vector store for metric/dimension discovery\n- `server/src/server/storage.py`: Conversation and message persistence\n- `server/src/server/chart_models.py`: Chart generation and configuration\n- `server/src/server/prompt.py`: Example queries and agent instructions\n\n### Conversation Context\n\nThe application supports setting conversation-level context that persists across all queries within a conversation. This allows users to:\n\n- Set default filters (e.g., \"Filter all results to 2023\")\n- Specify default ordering (e.g., \"Always order in ascending\")\n- Filter by specific dimensions (e.g., \"Only include the Automobile market segment\")\n- Require specific metrics in all queries (e.g., \"Always include revenue and profit\")\n\nThis context is intelligently applied to every query in the conversation, removing the need to repeatedly specify the same filters or preferences.\n\n### Query Examples\n\nThe system supports natural language queries like:\n- \"Show me total revenue\"\n- \"What was our monthly revenue and profit for 2023?\"\n- \"Who are our top 10 salespeople by revenue?\"\n- \"Show me revenue by region for US customers\"\n- \"What's our daily revenue trend for the past 30 days?\"\n\nWith context applied, simple queries automatically inherit the context settings:\n- Context: \"Filter to Q4-2023\" + Query: \"Show me revenue\" = Revenue filtered to Q4 2023\n- Context: \"Only US customers\" + Query: \"Top regions by profit\" = Top US regions by profit\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\nPlease make sure to update tests as appropriate.\n\n### Development Process\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## Acknowledgments\n\nThis project was built upon the [LangChain React Voice Agent](https://github.com/langchain-ai/react-voice-agent) repository, which provides the foundation for creating ReAct-style agents using OpenAI's Realtime API.\n\n## License\n\nThis project is licensed under the MIT License - see below for details:\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdpguthrie%2Fdbt-semantic-layer-voice-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdpguthrie%2Fdbt-semantic-layer-voice-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdpguthrie%2Fdbt-semantic-layer-voice-agent/lists"}