{"id":34588331,"url":"https://github.com/robkooper/robchat","last_synced_at":"2026-06-01T09:31:29.419Z","repository":{"id":287778889,"uuid":"965760050","full_name":"robkooper/robchat","owner":"robkooper","description":"simple rag chat application with frontend and backend.","archived":false,"fork":false,"pushed_at":"2025-04-13T21:26:35.000Z","size":50,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-13T22:19:04.048Z","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/robkooper.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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-04-13T21:01:07.000Z","updated_at":"2025-04-13T21:26:39.000Z","dependencies_parsed_at":"2025-04-13T22:19:10.444Z","dependency_job_id":"bbadb943-1caf-4e6c-9244-6731431868c7","html_url":"https://github.com/robkooper/robchat","commit_stats":null,"previous_names":["robkooper/robchat"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/robkooper/robchat","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robkooper%2Frobchat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robkooper%2Frobchat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robkooper%2Frobchat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robkooper%2Frobchat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/robkooper","download_url":"https://codeload.github.com/robkooper/robchat/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robkooper%2Frobchat/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33769490,"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-01T02:00:06.963Z","response_time":115,"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-12-24T10:47:19.562Z","updated_at":"2026-06-01T09:31:29.412Z","avatar_url":"https://github.com/robkooper.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RobChat\n\nA powerful Retrieval-Augmented Generation (RAG) system for document question answering. RobChat allows you to upload documents and ask questions about their content, receiving AI-generated answers with source citations.\n\n## TL;DR - Quick Start\n\n1. Clone and setup:\n   ```bash\n   git clone https://github.com/yourusername/robchat.git\n   cd robchat\n   python -m venv venv\n   source venv/bin/activate  # On Windows: venv\\Scripts\\activate\n   pip install -r requirements.txt\n   ```\n\n2. Configure:\n   - Copy `users.example.yaml` to `users.yaml`\n   - Copy `config.example.yaml` to `config.yaml`\n   - Update settings in both files if needed (optional)\n\n3. Run:\n   ```bash\n   uvicorn app:app --reload\n   ```\n\n4. Access:\n   - Open `http://localhost:8000` in your browser\n   - Login with default credentials (admin/secret or test/test)\n\n## Features\n\n- **Document Support**: Upload and process multiple document types:\n  - PDF files\n  - Word documents (DOCX)\n  - Text files (TXT)\n  - HTML files\n  - PowerPoint presentations (PPTX)\n  - Excel spreadsheets (XLSX)\n\n- **Advanced RAG Pipeline**:\n  - Document chunking and indexing\n  - Semantic search using embeddings\n  - Context-aware answer generation\n  - Source citations in responses\n\n- **Modern Tech Stack**:\n  - LangChain for RAG pipeline\n  - Llama2 (7B-Chat) for text generation\n  - sentence-transformers for embeddings\n  - ChromaDB for vector storage\n  - FastAPI for web API\n  - Bootstrap for responsive UI\n  - Vanilla JavaScript for frontend interactivity\n\n## Requirements\n\n- Python 3.9+\n- PyTorch\n- 16GB RAM minimum (32GB recommended)\n- GPU recommended but not required\n\n## Installation\n\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/yourusername/robchat.git\n   cd robchat\n   ```\n\n2. Create and activate a virtual environment:\n   ```bash\n   python -m venv venv\n   source venv/bin/activate  # On Windows: venv\\Scripts\\activate\n   ```\n\n3. Install dependencies:\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n4. Start the server:\n   ```bash\n   uvicorn app:app --reload\n   ```\n\n## Configuration\n\nThe application is configured using YAML files:\n\n1. `config.yaml` - Main configuration file\n2. `users.yaml` - User authentication configuration\n\nBoth configuration files are in `.gitignore` for security reasons. You need to create them from their example files:\n\n1. Copy `config.example.yaml` to `config.yaml`\n2. Copy `users.example.yaml` to `users.yaml`\n\n### Configuration Files\n\n#### config.yaml\nThe main configuration file contains settings for:\n- Data storage\n- Server configuration\n- Model settings\n- Vector store settings\n- Authentication settings\n- RAG settings\n\nExample configuration:\n```yaml\n# Data Storage\ndata:\n  base_directory: \"data\"\n  supported_extensions:\n    - \".pdf\"\n    - \".docx\"\n    - \".txt\"\n    - \".html\"\n    - \".pptx\"\n    - \".xlsx\"\n\n# Server Configuration\nserver:\n  host: \"0.0.0.0\"\n  port: 8000\n  log_level: \"info\"\n\n# Authentication Configuration\nauth:\n  secret_key: \"your-secret-key-here\"  # Change this in production!\n  algorithm: \"HS256\"\n  access_token_expire_minutes: 30\n\n# Models Configuration\nmodels:\n  llm:\n    repo_id: \"TheBloke/Llama-2-7B-Chat-GGUF\"\n    filename: \"llama-2-7b-chat.Q4_K_M.gguf\"\n    temperature: 0.7\n    max_tokens: 2000\n    context_window: 4096\n    top_p: 0.95\n    n_batch: 512\n  embeddings:\n    model_name: \"sentence-transformers/all-MiniLM-L6-v2\"\n    model_kwargs:\n      device: \"cpu\"\n\n# Vector Store Configuration\nvector_store:\n  chunk_size: 1000\n  chunk_overlap: 200\n  retrieval_k: 4\n\n# RAG Configuration\nrag:\n  qa_template: |\n    Use the following pieces of context to answer the question at the end.\n    If you don't know the answer based on the context, just say \"I don't know\" - do not try to make up an answer.\n    If you do know the answer, provide it clearly and concisely, incorporating relevant information from all provided sources.\n    Make sure to use all relevant information from the sources to give a complete answer.\n\n    Context:\n    {context}\n\n    Question: {question}\n\n    Answer: Let me help you with that.\n```\n\n#### users.yaml\nThe users configuration file contains user authentication information. This file should be kept secure and not committed to version control. A template is provided in `users.example.yaml`.\n\nExample configuration:\n```yaml\nadmin:\n  email: admin@example.com\n  fullname: Administrator\n  admin: true\n  password: $2b$12$EixZaYVK1fsbw1ZfbX3OXePaWxn96p36WQoeG6Lruj3vjPGga31lW  # password: secret\ntest:\n  email: test@example.com\n  fullname: Test User\n  admin: false\n  password: $2b$12$UCqQEFTUM/fTwhlnSa9c8OLbUrrmWv1tfyR/mHh7eWPdAxvDP/JKK  # password: test\n```\n\nTo set up users:\n1. Copy `users.example.yaml` to `users.yaml`\n2. Update the user information as needed\n3. Generate new password hashes using the `get_password_hash` function in `app.py`\n\nNote: The `users.yaml` file is automatically added to `.gitignore` to prevent accidental commits of sensitive information.\n\n### Data Storage\n- `base_directory`: Directory where uploaded files will be stored\n- `supported_extensions`: List of file types that can be processed\n\n### Server Configuration\n- `host`: Server host address (default: \"0.0.0.0\")\n- `port`: Server port (default: 8000)\n- `log_level`: Logging verbosity (debug, info, warning, error, critical)\n\n### Models Configuration\n- `llm`: Large Language Model settings\n  - `repo_id`: HuggingFace repository ID\n  - `filename`: Model filename\n  - `temperature`: Controls response randomness (0.0 to 1.0)\n  - `max_tokens`: Maximum response length\n  - `context_window`: Context size for processing\n  - `top_p`: Nucleus sampling parameter\n  - `n_batch`: Processing batch size\n- `embeddings`: Embedding model settings\n  - `model_name`: Model identifier\n  - `device`: Processing device (cpu, cuda, mps)\n\n### Vector Store Configuration\n- `chunk_size`: Size of text chunks for processing\n- `chunk_overlap`: Overlap between chunks\n- `retrieval_k`: Number of text chunks to retrieve per query (default: 4). Note that this is not the same as the number of source documents, as chunks may come from the same document and are deduplicated in the response.\n\nNote: The default values for these settings are optimized for typical use cases, but can be adjusted based on your needs. Increasing values like `context_window`, `retrieval_k`, or `chunk_size` may impact performance and memory usage. Adjust these settings based on your system's capabilities.\n\n### Document Processing and Retrieval\n\nThe system handles large documents and document sets through a chunking and retrieval process:\n\n1. **Document Chunking**:\n   - Documents are split into smaller chunks (controlled by `chunk_size`)\n   - Chunks overlap slightly (controlled by `chunk_overlap`)\n   - This maintains context between chunks while making text manageable\n\n2. **Retrieval Process**:\n   - Only the top `retrieval_k` chunks are retrieved for each query\n   - Chunks are selected based on semantic similarity to the query\n   - Not all documents/chunks are searched at once\n   - Focus is on the most relevant information\n\n3. **Context Window**:\n   - Limited by `context_window` setting (default: 4096 tokens)\n   - Includes both query and retrieved chunks\n   - May truncate content if limit is exceeded\n\nThis approach has both advantages and limitations:\n\n**Advantages**:\n- Efficient processing\n- Faster response times\n- Lower memory usage\n- Focus on most relevant information\n\n**Limitations**:\n- May miss relevant information in non-top chunks\n- Limited context for complex queries\n- May not capture relationships between distant document parts\n\nFor large document sets, consider:\n- Pre-filtering documents using metadata\n- Using document summaries\n- Implementing hierarchical search\n- Using document clustering\n\nAdjust settings in `config.yaml` to optimize for your needs:\n```yaml\nvector_store:\n  chunk_size: 2000     # Increase chunk size\n  chunk_overlap: 400   # Increase overlap\n  retrieval_k: 8       # Retrieve more chunks\n\nmodels:\n  llm:\n    context_window: 8192  # Increase context window\n```\n\nNote: Increasing these values will impact performance, memory usage, and response times.\n\n## Examples\n\nThe `example` folder contains demonstration scripts and sample documents to help you get started with the API:\n\n### Sample Documents\n- `quantum_computing.txt`: Information about quantum computing concepts and applications\n- `artificial_intelligence.txt`: Overview of AI technologies and their applications\n\n### API Usage Examples\n\n#### Python Example\nThe `test_api.py` script demonstrates how to:\n- Authenticate with the API\n- Upload documents\n- Query the documents\n- Handle responses\n\nRun the Python example:\n```bash\ncd example\npython test_api.py\n```\n\n#### Shell Script Example\nThe `test_api.sh` script provides the same functionality using curl commands:\n\nRun the shell script:\n```bash\ncd example\n./test_api.sh\n```\n\nNote: The shell script requires `curl` and `jq` to be installed.\n\n### Example Queries\nThe example scripts demonstrate three types of queries:\n1. Specific topic queries (e.g., \"What are the key concepts in quantum computing?\")\n2. Application queries (e.g., \"What are the main applications of AI?\")\n3. Combined topic queries (e.g., \"How can AI help with quantum computing?\")\n\n## Usage\n\n1. Start the server:\n     ```bash\n     uvicorn app:app --reload\n     ```\n\n2. Open your browser to `http://localhost:8000`\n\n3. Upload documents using the web interface\n\n4. Ask questions about your documents\n\n## API Endpoints\n\nAll endpoints require authentication using a Bearer token. To get a token:\n\n- `POST /token`\n  - Authenticate and get access token\n  - Body (form data): `username` and `password`\n  - Returns:\n    ```json\n    {\n      \"access_token\": \"token\",\n      \"token_type\": \"bearer\"\n    }\n    ```\n\nAll other endpoints follow the RESTful pattern `/api/{user}/{project}` where:\n- `{user}`: The username\n- `{project}`: The project name\n- All requests must include the header: `Authorization: Bearer \u003ctoken\u003e`\n\nAvailable endpoints:\n\n- `GET /api/{user}/projects`\n  - Lists all projects for a user and the current active project\n  - Returns:\n    ```json\n    {\n      \"projects\": [\"project1\", \"project2\"],\n      \"current_project\": \"project1\"\n    }\n    ```\n  - Error responses:\n    - 401: Not authenticated\n    - 403: Cannot access another user's projects\n\n- `GET /api/{user}/{project}/files`\n  - Lists all files in the project\n  - Returns:\n    ```json\n    {\n      \"files\": [\"file1.pdf\", \"file2.txt\"]\n    }\n    ```\n  - Error responses:\n    - 401: Not authenticated\n    - 403: Cannot access another user's files\n\n- `POST /api/{user}/{project}/files`\n  - Upload a new file to the project\n  - Accepts: multipart/form-data with file\n  - Supported file types: .pdf, .docx, .txt, .html, .pptx, .xlsx\n  - Returns:\n    ```json\n    {\n      \"filename\": \"file.txt\",\n      \"chunks\": 5,\n      \"initial_count\": 0,\n      \"final_count\": 5,\n      \"replaced_existing\": false\n    }\n    ```\n  - Error responses:\n    - 400: Unsupported file type\n    - 401: Not authenticated\n    - 403: Cannot upload to another user's project\n    - 500: File processing error\n\n- `DELETE /api/{user}/{project}/files/{filename}`\n  - Delete a file from the project\n  - Returns:\n    ```json\n    {\n      \"status\": \"success\",\n      \"message\": \"File \u003cfilename\u003e deleted successfully\"\n    }\n    ```\n  - Error responses:\n    - 401: Not authenticated\n    - 403: Cannot delete another user's files\n    - 404: File not found\n    - 500: Deletion error\n\n- `POST /api/{user}/{project}/query`\n  - Query the project's documents\n  - Body: `{\"text\": \"your question here\"}`\n  - Returns:\n    ```json\n    {\n      \"answer\": \"AI-generated answer\",\n      \"sources\": [\n        {\n          \"number\": 1,\n          \"file\": \"source1.pdf\",\n          \"text\": \"Full source text\",\n          \"preview\": \"First 150 characters...\"\n        }\n      ],\n      \"metrics\": {\n        \"time_seconds\": 1.23,\n        \"total_tokens\": 100,\n        \"input_tokens\": 20,\n        \"output_tokens\": 80\n      }\n    }\n    ```\n  - Error responses:\n    - 401: Not authenticated\n    - 403: Cannot query another user's documents\n    - 404: No documents found\n    - 422: Invalid query format\n    - 500: Query processing error\n\n## Project Structure\n\n```\nrobchat/\n├── app.py           # Main FastAPI application\n├── static/          # Static files\n│   ├── login.html   # Main entry point and login page\n│   ├── chat.html    # Chat interface\n│   ├── styles.css   # Global styles\n│   ├── app.js       # Main application logic\n│   ├── login.js     # Login functionality\n│   └── favicon.svg  # Site icon\n├── example/         # Example scripts and documents\n│   ├── test_api.py  # Python API example\n│   ├── test_api.sh  # Shell API example\n│   ├── quantum_computing.txt    # Sample document\n│   └── artificial_intelligence.txt  # Sample document\n├── data/           # Document storage\n│   └── {user}/\n│       └── {project}/\n│           └── chroma_db/  # Vector store\n├── tests/          # Test files\n│   ├── test_auth.py    # Authentication tests\n│   ├── test_files.py   # File operation tests\n│   └── test_projects.py # Project access control tests\n├── config.yaml     # Application configuration\n├── config.example.yaml  # Example configuration\n├── users.yaml      # User authentication configuration\n├── users.example.yaml  # Example user configuration\n├── requirements.txt # Python dependencies\n├── .gitignore      # Git ignore rules\n└── CHANGELOG.md    # Version history\n```\n\n## Error Handling\n\n- Automatic retry with exponential backoff for model operations\n- Graceful handling of file processing errors\n- Detailed error logging\n- Clean file cleanup on processing failures\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Commit your changes\n4. Push to the branch\n5. Create a Pull Request\n\n## License\n\nMIT License - see LICENSE file for details","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobkooper%2Frobchat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobkooper%2Frobchat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobkooper%2Frobchat/lists"}