{"id":43305110,"url":"https://github.com/langwatch/data-analytics-agent","last_synced_at":"2026-02-01T20:14:04.523Z","repository":{"id":329962116,"uuid":"1116928227","full_name":"langwatch/data-analytics-agent","owner":"langwatch","description":"SQL Analytics agent","archived":false,"fork":false,"pushed_at":"2025-12-22T14:19:13.000Z","size":188,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-24T01:16:35.675Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/langwatch.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,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-15T15:25:04.000Z","updated_at":"2025-12-22T14:08:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/langwatch/data-analytics-agent","commit_stats":null,"previous_names":["langwatch/data-analytics-agent"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/langwatch/data-analytics-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/langwatch%2Fdata-analytics-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/langwatch%2Fdata-analytics-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/langwatch%2Fdata-analytics-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/langwatch%2Fdata-analytics-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/langwatch","download_url":"https://codeload.github.com/langwatch/data-analytics-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/langwatch%2Fdata-analytics-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28988635,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-01T18:17:03.387Z","status":"ssl_error","status_checked_at":"2026-02-01T18:16:57.287Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":"2026-02-01T20:14:03.854Z","updated_at":"2026-02-01T20:14:04.499Z","avatar_url":"https://github.com/langwatch.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Data Analytics Agent\r\n\r\nA production-ready AI agent that safely answers data questions by querying a Postgres database, returning structured results, and rendering them in an interactive web UI. Built with Mastra framework and TypeScript, following Better Agents best practices.\r\n\r\n## Features\r\n\r\n- **Natural Language Querying**: Ask questions in plain English about your data\r\n- **Safe SQL Generation**: Automatically generates and executes secure SQL queries\r\n- **Structured Results**: Returns data in JSON, tables, and charts\r\n- **Interactive UI**: Web-based interface for exploring results\r\n- **Multi-turn Conversations**: Supports follow-up questions and query refinements\r\n- **Error Handling**: Graceful handling of invalid queries and database errors\r\n- **Comprehensive Testing**: End-to-end scenario tests and evaluations\r\n- **Instrumentation**: Full LangWatch integration for monitoring and analytics\r\n\r\n## Prerequisites\r\n\r\n- Node.js 18+\r\n- pnpm package manager\r\n- PostgreSQL database\r\n- API keys for:\r\n  - OpenAI (or other LLM provider)\r\n  - LangWatch\r\n\r\n## Installation\r\n\r\n1. Clone the repository:\r\n```bash\r\ngit clone \u003crepository-url\u003e\r\ncd data-analytics-agent\r\n```\r\n\r\n2. Install dependencies:\r\n```bash\r\npnpm install\r\n```\r\n\r\n3. Copy environment variables:\r\n```bash\r\ncp .env.example .env\r\n```\r\n\r\n4. Fill in your API keys and database connection details in `.env`:\r\n```env\r\nOPENAI_API_KEY=your_openai_api_key\r\nLANGWATCH_API_KEY=your_langwatch_api_key\r\nDATABASE_URL=postgresql://user:password@localhost:5432/database\r\n```\r\n\r\n## Setup\r\n\r\n1. Ensure your PostgreSQL database is running and accessible.\r\n\r\n2. Install LangWatch CLI globally:\r\n```bash\r\npnpm add -g @langwatch/cli\r\n```\r\n\r\n3. Sync prompts:\r\n```bash\r\nlangwatch prompt sync\r\n```\r\n\r\n## Usage\r\n\r\n### Running the Agent\r\n\r\nStart the development server:\r\n```bash\r\npnpm dev\r\n```\r\n\r\nThe agent will be available at `http://localhost:3000` (or the configured port).\r\n\r\n### Interacting with the Agent\r\n\r\n1. Open your browser and navigate to the agent URL\r\n2. Ask questions in natural language, such as:\r\n   - \"What are the total sales by month?\"\r\n   - \"Show me customers with orders over $1000\"\r\n   - \"What's the average order value by product category?\"\r\n\r\n3. The agent will:\r\n   - Generate a safe SQL query\r\n   - Execute it against your database\r\n   - Return structured results\r\n   - Display them in an interactive UI\r\n\r\n### API Usage\r\n\r\nThe agent exposes REST endpoints for programmatic access:\r\n\r\n```typescript\r\n// Example API call\r\nconst response = await fetch('/api/query', {\r\n  method: 'POST',\r\n  headers: { 'Content-Type': 'application/json' },\r\n  body: JSON.stringify({\r\n    question: \"What are the top 10 products by sales?\"\r\n  })\r\n});\r\n\r\nconst result = await response.json();\r\n```\r\n\r\n## Testing\r\n\r\n### Scenario Tests\r\n\r\nRun end-to-end scenario tests:\r\n```bash\r\npnpm test:scenarios\r\n```\r\n\r\n### Unit Tests\r\n\r\nRun unit tests with vitest:\r\n```bash\r\npnpm test\r\n```\r\n\r\n### Evaluations\r\n\r\nRun evaluation notebooks:\r\n```bash\r\n# Requires Jupyter\r\njupyter notebook tests/evaluations/\r\n```\r\n\r\n## Development\r\n\r\n### Project Structure\r\n\r\n```\r\n├── app/                 # Main application code\r\n│   └── index.ts        # Agent entry point\r\n├── prompts/            # Versioned prompt files (YAML)\r\n├── tests/\r\n│   ├── evaluations/    # Jupyter notebooks for evaluations\r\n│   └── scenarios/      # End-to-end scenario tests\r\n├── prompts.json        # Prompt registry\r\n├── .env               # Environment variables\r\n└── AGENTS.md          # Development guidelines\r\n```\r\n\r\n### Adding New Features\r\n\r\n1. **Understand Requirements**: Clarify what the agent should do\r\n2. **Design the Approach**: Plan components needed\r\n3. **Implement with Prompts**: Use LangWatch Prompt CLI for prompts\r\n4. **Write Tests**: Create scenario tests for validation\r\n5. **Run Tests**: Verify everything works\r\n\r\n### Prompt Management\r\n\r\nAll prompts are managed via LangWatch Prompt CLI:\r\n\r\n```bash\r\n# Create a new prompt\r\nlangwatch prompt create my_new_prompt\r\n\r\n# Edit the YAML file in prompts/\r\n# Then sync\r\nlangwatch prompt sync\r\n```\r\n\r\n### Database Schema\r\n\r\nThe agent expects a standard e-commerce schema. Update the prompts and agent logic if your schema differs.\r\n\r\nExample schema:\r\n- `customers` table\r\n- `orders` table\r\n- `order_items` table\r\n- `products` table\r\n\r\n## Configuration\r\n\r\n### Environment Variables\r\n\r\n- `OPENAI_API_KEY`: Your OpenAI API key\r\n- `LANGWATCH_API_KEY`: LangWatch API key for instrumentation\r\n- `DATABASE_URL`: PostgreSQL connection string\r\n- `PORT`: Server port (default: 3000)\r\n\r\n### Database Connection\r\n\r\nConfigure your Postgres connection in `.env`. The agent uses connection pooling for performance.\r\n\r\n## Monitoring\r\n\r\nThe agent is fully instrumented with LangWatch for:\r\n\r\n- Query performance monitoring\r\n- Error tracking\r\n- Usage analytics\r\n- Prompt optimization\r\n\r\nAccess the LangWatch dashboard at https://app.langwatch.ai/\r\n\r\n## Contributing\r\n\r\n1. Follow the guidelines in `AGENTS.md`\r\n2. Use LangWatch Prompt CLI for prompt management\r\n3. Write scenario tests for new features\r\n4. Run all tests before submitting PRs\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the LICENSE file for details.\r\n\r\n## Resources\r\n\r\n- [AGENTS.md](AGENTS.md) - Development guidelines\r\n- [LangWatch Documentation](https://docs.langwatch.ai/)\r\n- [Mastra Framework](https://mastra.ai/)\r\n- [Vercel AI SDK](https://ai-sdk.dev/)\r\n- [Scenario Testing](https://scenario.langwatch.ai/)\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flangwatch%2Fdata-analytics-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flangwatch%2Fdata-analytics-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flangwatch%2Fdata-analytics-agent/lists"}