{"id":30145134,"url":"https://github.com/ryu-ryuk/kyoka","last_synced_at":"2026-06-08T16:05:05.071Z","repository":{"id":304200390,"uuid":"1018086166","full_name":"ryu-ryuk/kyoka","owner":"ryu-ryuk","description":"a CLI-first system that leverages Large Language Models (LLMs) to interpret natural language queries and retrieve relevant information from complex, unstructured insurance documents (PDFs, DOCX, emails)","archived":false,"fork":false,"pushed_at":"2025-07-27T07:35:35.000Z","size":71,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-08-11T08:23:34.715Z","etag":null,"topics":["cli","decision-making","llm","parser","python","rag","reasoning"],"latest_commit_sha":null,"homepage":"","language":"Python","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/ryu-ryuk.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-07-11T15:25:41.000Z","updated_at":"2025-07-27T07:35:39.000Z","dependencies_parsed_at":"2025-07-11T17:50:02.273Z","dependency_job_id":"fbd73a58-a46c-4e9b-8c67-17dfe8ea18e2","html_url":"https://github.com/ryu-ryuk/kyoka","commit_stats":null,"previous_names":["ryu-ryuk/kyoka"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ryu-ryuk/kyoka","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryu-ryuk%2Fkyoka","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryu-ryuk%2Fkyoka/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryu-ryuk%2Fkyoka/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryu-ryuk%2Fkyoka/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ryu-ryuk","download_url":"https://codeload.github.com/ryu-ryuk/kyoka/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryu-ryuk%2Fkyoka/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34069504,"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-08T02:00:07.615Z","response_time":111,"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":["cli","decision-making","llm","parser","python","rag","reasoning"],"created_at":"2025-08-11T08:09:29.281Z","updated_at":"2026-06-08T16:05:05.054Z","avatar_url":"https://github.com/ryu-ryuk.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg width=\"1212\" height=\"363\" alt=\"Image\" src=\"https://github.com/user-attachments/assets/d4a2cee5-907d-49bf-9f3c-d2132336bd0a\" /\u003e\n\u003c/div\u003e\n\n\u003ch1 align=\"center\"\u003eKyoka\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\u003ci\u003e\nthe name \u003cb\u003ekyoka\u003c/b\u003e (狂歌, “mad poem”) reflects the system’s role in turning formal documents into intelligent, structured responses — just as \u003cb\u003ekyōka\u003c/b\u003e poetry reimagines tradition with clarity and wit.\n\u003c/i\u003e\u003c/p\u003e\n\n---\n\n**Kyoka** is a high-performance RAG system that processes documents and answers complex queries with precise, source-cited responses. Built for insurance, legal, HR, and compliance domains.\n\n\n## Features\n\n- **Multi-format Support**: PDF, DOCX, and email document processing\n- **Hybrid Retrieval**: Combines dense (Pinecone) and sparse (BM25) search for superior accuracy\n- **Semantic Chunking**: Intelligent text splitting with contextual overlap\n- **Re-ranking**: Uses Flashrank for refined result relevance\n- **Structured Responses**: JSON output with answers, rationale, and source attribution\n- **Async Processing**: Concurrent question handling for optimal performance\n- **GPU Acceleration**: CUDA support for faster embedding generation\n- **Intelligent Caching**: Document and retriever caching for repeated queries\n\n## Architecture\n\nThe system operates in two phases:\n\n1. **Document Ingestion**: Structured parsing → Semantic chunking → Vector embedding → Pinecone indexing\n2. **Query Processing**: Hybrid retrieval → Re-ranking → LLM generation → Structured response\n\n#### Preview\n\n\u003cimg width=\"728\" height=\"554\" alt=\"Untitled-2025-07-22-1029(2)\" src=\"https://github.com/user-attachments/assets/c941e652-70c6-408c-8b75-655e2a8f89fe\" /\u003e\n\n\n---\n\n\u003cdetails\u003e\n  \u003csummary\u003eView Detailed Architecture Diagram\u003c/summary\u003e\n  \u003cimg width=\"1420\" height=\"2493\" alt=\"Untitled-2025-07-22-1029(1)\" src=\"https://github.com/user-attachments/assets/e37689fb-f21c-48bc-81f7-22c27eda61da\" /\u003e\n\u003c/details\u003e\n\n\n\n\n## Tech Stack\n\n- **Backend**: FastAPI\n- **Vector Database**: Pinecone\n- **LLM**: Google Gemini 1.5 Flash\n- **Embeddings**: HuggingFace (intfloat/e5-small-v2)\n- **Re-ranker**: Flashrank (ms-marco-TinyBERT-L-2-v2)\n- **Document Processing**: PyMuPDF, python-docx\n- **Framework**: LangChain\n\n## Setup\n\n1. **Install Dependencies**\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n2. **Environment Configuration**\n   \n   Create a `.env` file:\n   ```env\n   PINECONE_API_KEY=your_pinecone_api_key\n   GEMINI_API_KEY=your_gemini_api_key\n   ```\n\n3. **Run the Application**\n   ```bash\n   python main.py\n   ```\n\n## API Endpoints\n\n### Process Document from URL\n**POST** `/hackrx/run`\n\n```json\n{\n  \"documents\": \"https://neow.com/document.pdf\",\n  \"questions\": [\"What is the grace period?\", \"What are the waiting periods?\"]\n}\n```\n\n### Upload Document File\n**POST** `/hackrx/upload`\n\n```bash\ncurl -X POST \"http://localhost:8000/hackrx/upload\" \\\n     -F \"file=@document.pdf\" \\\n     -F \"questions=What is the grace period?\" \\\n     -F \"questions=What are the waiting periods?\"\n```\n\n### Response Format\n```json\n{\n  \"answers\": [\n    {\n      \"query\": \"What is the grace period?\",\n      \"answer\": \"A 15-day grace period is provided for installment premium payments...\",\n      \"rationale\": \"Based on policy document analysis of premium payment terms\",\n      \"source\": \"page 31, page 3\"\n    }\n  ]\n}\n```\n\n## Performance\n\n- **Response Time**: ~8.5 seconds for 2 questions (with caching: ~4.5 seconds)\n- **Supported Formats**: PDF, DOCX, email (.eml, .msg, .txt)\n- **Concurrent Processing**: Up to 8 parallel questions\n- **GPU Acceleration**: 3-5x faster embedding generation\n\n## Configuration\n\nKey parameters can be adjusted in `constants.py`:\n\n```python\nMAX_CHUNK_TOKENS = 500          # Chunk size for processing speed\nMAX_CONTEXT_CHUNKS = 3          # Context chunks sent to LLM\nCONCURRENT_QUESTION_LIMIT = 8   # Parallel question processing\nGEMINI_MAX_OUTPUT_TOKENS = 300  # Response length limit\n```\n\n## Evaluation Criteria Compliance\n\n- **Accuracy**: Hybrid retrieval + re-ranking ensures precise context matching\n- **Token Efficiency**: Optimized chunking and context selection minimizes LLM usage\n- **Latency**: Async processing and caching deliver sub-10-second responses\n- **Reusability**: Modular design with configurable components\n- **Explainability**: Structured responses with rationale and source traceability\n\n## Health Check\n\n```bash\ncurl http://localhost:8000/health\n```\n\nReturns system status, GPU availability, cache statistics, and configuration details.\n\n## License\n\n[License](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryu-ryuk%2Fkyoka","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fryu-ryuk%2Fkyoka","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryu-ryuk%2Fkyoka/lists"}