{"id":24794093,"url":"https://github.com/njaffe/mtg_judgebot","last_synced_at":"2026-04-13T13:02:25.993Z","repository":{"id":239091436,"uuid":"798506617","full_name":"njaffe/mtg_judgebot","owner":"njaffe","description":"RAG-powered LLM chatbot using RAG, external API calls, and FastAPI.","archived":false,"fork":false,"pushed_at":"2025-10-23T17:11:45.000Z","size":163124,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-29T02:40:53.877Z","etag":null,"topics":["api","fastapi","llms","python","rag","vector-database"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","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/njaffe.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-05-09T23:13:02.000Z","updated_at":"2025-10-15T16:37:56.000Z","dependencies_parsed_at":null,"dependency_job_id":"933bd7b3-6b0d-463a-b7a9-5a8900884f37","html_url":"https://github.com/njaffe/mtg_judgebot","commit_stats":null,"previous_names":["njaffe/ragpractice","njaffe/mtg_judgebot"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/njaffe/mtg_judgebot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njaffe%2Fmtg_judgebot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njaffe%2Fmtg_judgebot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njaffe%2Fmtg_judgebot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njaffe%2Fmtg_judgebot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/njaffe","download_url":"https://codeload.github.com/njaffe/mtg_judgebot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njaffe%2Fmtg_judgebot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31753551,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T09:16:15.125Z","status":"ssl_error","status_checked_at":"2026-04-13T09:16:05.023Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["api","fastapi","llms","python","rag","vector-database"],"created_at":"2025-01-29T22:32:51.120Z","updated_at":"2026-04-13T13:02:25.962Z","avatar_url":"https://github.com/njaffe.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Magic: The Gathering AI Judge\n\nAn AI-powered tool designed to assist with complex rules scenarios and edge cases in Magic: The Gathering.\n\n## Table of Contents\n\n- Overview\n- Features\n- Installation\n- Usage\n- Project Structure\n- Future Improvements\n- Contributing\n- License\n\n## Overview\n\nThis project implements a Retrieval-Augmented Generation (RAG) system to create an AI “judge” for Magic: The Gathering (MTG). The tool helps players and enthusiasts navigate the complex rules and edge cases that often arise in the game. By leveraging large language models (LLMs) and a comprehensive rules database, this AI judge provides quick and accurate answers to MTG-related queries.\n\nThe system uses agents within the RAG framework to query various sources, including a custom database of MTG rules, as well as external platforms like Reddit and Google, to gather relevant context and insights. The AI then generates a combined answer, ensuring players have access to both authoritative rules information and community perspectives.\n\n## Features\n\n- RAG-based query system: Utilizes the entire MTG rules corpus (approximately 148,000 words).\n- Integration with external sources: Queries Reddit and Google for additional context and community insights.\n- Multi-source answer compilation: Combines results from the rules corpus, Reddit, and Google searches for more robust answers.\n- Agent-based architecture: Uses agents as part of the RAG framework to optimize information retrieval and answer generation.\n- Natural language processing: Understands and responds to MTG-specific queries in natural language, providing intuitive answers.\n\n## Installation\n\n### Prerequisites\n\n- Python 3.7+\n- Environment variables configured (see .env file for API keys)\n\n### Steps\n\n1. Clone the repository:\n\n\t```sh\n\tgit clone https://github.com/your-repo/mtg-ai-judge.git\n\tcd mtg-ai-judge\n\t```\n\n2. Create and activate a virtual environment:\n\n\t```sh\n\tpython3 -m venv venv\n\tsource venv/bin/activate\n\t```\n\n3. Install the required packages:\n\n\t```sh\n\tpip install -r requirements.txt\n\t```\n\n4. Set up your environment variables in a `.env` file (refer to the `.env.sample` file in the repo):\n\n\t```env\n\tOPENAI_API_KEY=your_openai_api_key\n\tGOOGLE_CSE_ID=your_google_cse_id\n\tGOOGLE_API_KEY=your_google_api_key\n\tREDDIT_CLIENT_ID=your_reddit_client_id\n\tREDDIT_CLIENT_SECRET=your_reddit_client_secret\n\tREDDIT_USER_AGENT=your_reddit_user_agent\n\t```\n\n## Usage\n\n### Quick Start\n\n1. **Activate your virtual environment:**\n   ```sh\n   source venv/bin/activate\n   ```\n\n2. **Ask a question:**\n   ```sh\n   python src/cli/main.py --query_text \"What happens when a creature dies?\"\n   ```\n\n3. **That's it!** The AI Judge will query multiple sources and give you a comprehensive answer.\n\n### Command Line Usage\n\n#### Basic Query\n```bash\n# Ask a simple question\npython src/cli/main.py --query_text \"What happens when a creature dies?\"\n\n# Ask a complex rules question\npython src/cli/main.py --query_text \"If I have a creature with an equipment on it, and an opponent gains control of the creature, what happens?\"\n```\n\n#### Advanced Options\n```bash\n# Run test suite\npython src/cli/main.py --test_mode --start 0 --end 5\n\n# Refresh the RAG database\npython src/cli/main.py --refresh_db\n\n# Customize Reddit search\npython src/cli/main.py --query_text \"Your question\" --subreddit \"mtgrules\" --limit 20\n```\n\n#### All Available Options\n```bash\npython src/cli/main.py --help\n```\n\n### Programmatic Usage\n\n#### Using the CLI Programmatically\n```python\nfrom src.cli.main import MTGJudgeCLI\n\n# Initialize the CLI\ncli = MTGJudgeCLI()\n\n# Ask a single question\nresult = cli.run_single_query(\"What happens when a creature dies?\")\nprint(result['final_answer'])\n\n# Run test suite programmatically\nresults = cli.run_test_suite(start=0, end=5)\nfor result in results:\n    print(f\"Q: {result['query']}\")\n    print(f\"A: {result['response']}\\n\")\n```\n\n#### Using Individual Services\n```python\nfrom src.core.synthesis_service import SynthesisService\nfrom src.core.rag_service import RAGService\nfrom src.external.google_client import GoogleClient\nfrom src.external.reddit_client import RedditClient\n\n# Initialize services\nsynthesis = SynthesisService()\nrag = RAGService()\ngoogle = GoogleClient()\nreddit = RedditClient()\n\n# Query individual sources\nrag_response = rag.query(\"Your question here\")\ngoogle_response = google.search(\"Your question here\")\nreddit_response = reddit.search(\"Your question here\")\n\n# Synthesize the final answer\nfinal_answer = synthesis.synthesize_response(\n    rag_response, google_response, reddit_response, \"Your question here\"\n)\nprint(final_answer)\n```\n\n### Web Interface\n\nYou can also use the Streamlit web interface:\n\n```bash\nstreamlit run streamlit_app.py\n```\n\nThis provides a user-friendly web interface for asking questions.\n\n\n## Project Structure\n\nThe project follows a clean, service-based architecture with clear separation of concerns:\n\n```\nmtg_judgebot/\n├── src/                          # Source code\n│   ├── core/                    # Core business logic\n│   │   ├── synthesis_service.py # Answer synthesis\n│   │   ├── rag_service.py       # RAG database operations\n│   │   └── indexers.py         # Database indexing\n│   ├── external/                # External API integrations\n│   │   ├── google_client.py    # Google Search API\n│   │   ├── reddit_client.py    # Reddit API\n│   │   └── openai_client.py    # OpenAI API\n│   ├── cli/                     # Command-line interface\n│   │   └── main.py             # CLI entry point\n│   └── utils/                   # Utility functions\n├── data/                        # Data storage\n│   ├── raw_docs/               # Raw documents\n│   ├── indices/                # FAISS indices\n│   └── tests/                   # Test data\n├── streamlit_app.py            # Web interface\n├── requirements.txt            # Dependencies\n└── .env                       # Configuration\n```\n\n## Contributing\n\nContributions are welcome! Please fork the repository, create a new branch, and submit a pull request.\n\n## License\n\nThis project is licensed under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnjaffe%2Fmtg_judgebot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnjaffe%2Fmtg_judgebot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnjaffe%2Fmtg_judgebot/lists"}