{"id":29242755,"url":"https://github.com/webobite/custom-data-query-agent","last_synced_at":"2025-07-03T20:35:37.239Z","repository":{"id":293646133,"uuid":"984696624","full_name":"webobite/custom-data-query-agent","owner":"webobite","description":null,"archived":false,"fork":false,"pushed_at":"2025-05-16T11:53:23.000Z","size":42,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-16T12:24:14.834Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/webobite.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-05-16T11:02:09.000Z","updated_at":"2025-05-16T11:53:26.000Z","dependencies_parsed_at":"2025-05-22T04:30:52.328Z","dependency_job_id":null,"html_url":"https://github.com/webobite/custom-data-query-agent","commit_stats":null,"previous_names":["webobite/custom-data-query-agent"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/webobite/custom-data-query-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webobite%2Fcustom-data-query-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webobite%2Fcustom-data-query-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webobite%2Fcustom-data-query-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webobite%2Fcustom-data-query-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/webobite","download_url":"https://codeload.github.com/webobite/custom-data-query-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webobite%2Fcustom-data-query-agent/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263401150,"owners_count":23461054,"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":"2025-07-03T20:35:26.661Z","updated_at":"2025-07-03T20:35:37.231Z","avatar_url":"https://github.com/webobite.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Natural Language Query Agent\n\nA powerful TypeScript-based CLI application that allows querying data using natural language, powered by Ollama's local LLM. This application provides an intuitive interface for interacting with CSV data through natural language queries, with a Python FastAPI backend for data processing.\n\n## ✨ Features\n\n- **Natural Language Processing**: Convert plain English queries into structured database filters using Ollama's LLM\n- **Advanced Querying**: Supports complex queries with multiple conditions, ranges, and sorting\n- **RESTful API**: FastAPI backend with proper error handling and response formatting\n- **Type Safety**: Full TypeScript support with proper type definitions\n- **Rich Output**: Beautifully formatted tables with syntax highlighting\n- **Robust Error Handling**: Comprehensive error handling and user feedback\n- **Case-Insensitive Matching**: Smart filtering that handles case variations in text fields\n- **Extensible Architecture**: Modular design for easy extension\n\n## 🚀 Prerequisites\n\n1. **Node.js 18 or higher**\n2. **Ollama** installed and running locally\n3. **Python 3.8+** with pip\n4. **Required Python packages**:\n   ```bash\n   pip install fastapi uvicorn pandas python-multipart\n   ```\n5. **Backend server** running on port 8000 (from the parent directory)\n\n## 🛠️ Setup\n\n1. **Clone the repository** (if you haven't already):\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd custom-data-query-agent\n   ```\n\n2. **Set up the Python backend**:\n   ```bash\n   cd mcp-server-python\n   pip install -r requirements.txt\n   ```\n\n3. **Set up the TypeScript frontend**:\n   ```bash\n   cd ../mcp-agent-typescript\n   npm install\n   npm run build\n   ```\n\n4. **Set up Ollama**:\n   - Install Ollama by following the instructions at: [https://ollama.ai/](https://ollama.ai/)\n   - Start the Ollama server in a separate terminal:\n     ```bash\n     ollama serve\n     ```\n   - Pull the required model (llama3 is recommended):\n     ```bash\n     ollama pull llama3\n     ```\n\n## 🏃‍♂️ Running the Application\n\n1. **Start the Python backend server**:\n   ```bash\n   cd mcp-server-python\n   uvicorn main:app --reload\n   ```\n   The server will start on `http://localhost:8000`\n\n2. **Start the TypeScript application** in a new terminal:\n   ```bash\n   cd mcp-agent-typescript\n   npm run dev\n   ```\n   Or for production:\n   ```bash\n   npm start\n   ```\n\n3. **Enter your natural language queries** at the prompt. For example:\n   ```\n   \u003e Show me all employees in Engineering\n   \u003e Find people with more than 100 project hours\n   \u003e List all employees in Marketing\n   \u003e Show employees with project hours between 50 and 150\n   ```\n\n4. **Useful commands**:\n   - `help` - Show help information\n   - `exit` - Quit the application\n\n## 📚 Query Examples\n\nHere are some example queries you can try:\n\n- Basic filtering:\n  ```\n  \u003e Show me all employees in the Engineering department\n  \u003e Find people with the role \"Senior Developer\"\n  \u003e List all active employees\n  ```\n\n- Numeric ranges:\n  ```\n  \u003e Show employees with 20-40 project hours\n  \u003e Find people with more than 30 project hours\n  \u003e List employees with less than 10 project hours -- giving wrong result\n  ```\n\n- Date ranges:\n  ```\n  \u003e Show employees who joined after January 2023 - giving wrong result\n  \u003e Find people who joined between 2022 and 2023\n  ```\n\n- Sorting and limiting:\n  ```\n  \u003e Show the top 5 employees by project hours\n  \u003e List employees sorted by name in descending order\n  \u003e Show the 10 most recent hires -- # this is still giving error\n  ```\n\n- Combined queries:\n  ```\n  \u003e Find active employees in Engineering with more than 20 project hours\n  \u003e Show me managers in the Sales department who joined in the last year -- # this is still giving error\n  ```\n\n## 🧩 Project Structure\n\n```\ncustom-data-query-agent/\n├── mcp-agent-typescript/    # TypeScript frontend\n│   ├── src/\n│   │   ├── config/         # Configuration files\n│   │   │   └── llmConfig.ts  # LLM model configuration\n│   │   ├── services/         # Service layer\n│   │   │   ├── nlpService.ts        # Natural language processing\n│   │   │   └── queryServiceClient.ts # API client for the backend\n│   │   └── index.ts          # Main application entry point\n│   └── package.json\n│\n└── mcp-server-python/      # Python FastAPI backend\n    ├── data/               # Sample data files\n    ├── main.py             # FastAPI application\n    └── requirements.txt    # Python dependencies\n```\n\n## 🔧 Configuration\n\n### Frontend Configuration (`mcp-agent-typescript/src/config/llmConfig.ts`)\n- `model`: The Ollama model to use (default: 'llama3')\n- `temperature`: Controls randomness in the LLM's responses (0.0 to 1.0)\n- `maxTokens`: Maximum number of tokens to generate\n- `systemPrompt`: Instructions for the LLM on how to process queries\n\n### Backend Configuration (`mcp-server-python/main.py`)\n- `DATA_FILE_PATH`: Path to the CSV data file\n- `SERVER_HOST` and `SERVER_PORT`: Server binding configuration\n- `DEBUG_MODE`: Enable/disable debug logging\n\n## 🐛 Debugging\n\n### Frontend Debugging\n```bash\n# Enable debug logging\nDEBUG=* npm start\n\n# Or run in development mode with auto-reload\nnpm run dev\n```\n\n### Backend Debugging\n```bash\n# Run server with debug logging\ncd mcp-server-python\nuvicorn main:app --reload --log-level debug\n\n# Or run with Python directly for more control\npython -m uvicorn main:app --reload --log-level debug\n```\n\n### Common Issues\n1. **Ollama not running**: Ensure Ollama server is running with `ollama serve`\n2. **Python dependencies**: Run `pip install -r requirements.txt` if you get import errors\n3. **Port conflicts**: Check if port 8000 is available for the Python server\n4. **CORS issues**: Ensure the frontend is making requests to the correct backend URL\n\n## 🤝 Contributing\n\nWe welcome contributions! Here's how to get started:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Run tests and ensure code quality:\n   ```bash\n   # TypeScript\n   npm run lint\n   npm test\n   \n   # Python\n   flake8 .\n   ```\n5. Commit your changes with a clear message (`git commit -m 'feat: add amazing feature'`)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n### Commit Message Guidelines\nWe follow [Conventional Commits](https://www.conventionalcommits.org/):\n- `feat:` for new features\n- `fix:` for bug fixes\n- `docs:` for documentation changes\n- `style:` for formatting changes\n- `refactor:` for code changes that neither fix bugs nor add features\n- `test:` for adding tests\n- `chore:` for maintenance tasks\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Ollama](https://ollama.ai/) for the powerful local LLM\n- [Node.js](https://nodejs.org/) and [TypeScript](https://www.typescriptlang.org/) for the runtime and type safety\n- [Chalk](https://github.com/chalk/chalk) for beautiful terminal output\n- [Table](https://github.com/gajus/table) for formatted table output\n\n## 🚀 Example Queries\n\n### Basic Queries\n- \"Show me all employees in Engineering\"\n- \"Find people with more than 100 project hours\"\n- \"List all employees in Marketing\"\n\n### Advanced Queries\n- \"Show engineers with project hours between 50 and 150\"\n- \"List employees sorted by project hours (highest first)\"\n- \"Find people in Engineering with more than 100 project hours\"\n\n## 📊 Data Model\n\nThe application works with employee data containing the following fields:\n- `id`: Unique identifier (number)\n- `name`: Employee name (string)\n- `department`: Department name (string)\n- `project_hours`: Number of hours worked on projects (number)\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebobite%2Fcustom-data-query-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebobite%2Fcustom-data-query-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebobite%2Fcustom-data-query-agent/lists"}