Spaces:
No application file
No application file
| title: IFX-sandbox | |
| emoji: 🏈 | |
| colorFrom: red | |
| colorTo: gray | |
| sdk: gradio | |
| app_file: gradio_app.py | |
| pinned: false | |
| # 49ers FanAI Hub - Gradio Version | |
| This is a Gradio-based chatbot application that provides information about the San Francisco 49ers, players, games, and fans. The application uses LangChain, Neo4j, and Zep for memory management. | |
| ## Features | |
| - Chat interface for asking questions about the 49ers | |
| - Integration with Neo4j graph database for structured data queries | |
| - Vector search for finding game summaries | |
| - Memory management with Zep for conversation history | |
| - Game Recap component that displays visual information for game-related queries | |
| ## Prerequisites | |
| - Python 3.9+ | |
| - Neo4j database (local or Aura) | |
| - OpenAI API key | |
| - Zep API key | |
| ## Installation | |
| 1. Clone the repository | |
| 2. Install the required packages: | |
| ```bash | |
| pip install -r gradio_requirements.txt | |
| ``` | |
| 3. Set up your environment variables: | |
| - Copy `.env.example` to `.env` in the root directory | |
| - Fill in your API keys and credentials | |
| Example `.env` file: | |
| ``` | |
| OPENAI_API_KEY=your_openai_api_key | |
| OPENAI_MODEL=gpt-4o | |
| AURA_CONNECTION_URI=your_neo4j_uri | |
| AURA_USERNAME=your_neo4j_username | |
| AURA_PASSWORD=your_neo4j_password | |
| ZEP_API_KEY=your_zep_api_key | |
| ``` | |
| > **IMPORTANT**: Never commit your actual API keys or credentials to the repository. The `.env` files are included in `.gitignore` to prevent accidental exposure of sensitive information. | |
| ## Running the Application | |
| To run the Gradio application: | |
| ```bash | |
| python gradio_app.py | |
| ``` | |
| This will start the Gradio server and open the application in your default web browser. | |
| ## Project Structure | |
| - `gradio_app.py`: Main Gradio application | |
| - `gradio_agent.py`: Agent implementation using LangChain for Gradio | |
| - `gradio_graph.py`: Neo4j graph connection for Gradio | |
| - `gradio_llm.py`: Language model configuration for Gradio | |
| - `gradio_utils.py`: Utility functions for Gradio | |
| - `prompts.py`: System prompts for the agent | |
| - `tools/`: Specialized tools for the agent | |
| - `cypher.py`: Tool for Cypher queries to Neo4j | |
| - `vector.py`: Tool for vector search of game summaries | |
| - `game_recap.py`: Tool for game recaps with visual component | |
| - `components/`: UI components | |
| - `game_recap_component.py`: Game recap visual component | |
| - `data/`: Data files and scripts | |
| - Various scripts and CSV files with 49ers data | |
| - `docs/`: Documentation | |
| - `requirements.md`: Detailed product and technical requirements | |
| - `game_recap_implementation_instructions.md`: Implementation details for the game recap feature | |
| ## Game Recap Component | |
| The Game Recap feature provides visual information about games in addition to text-based summaries. When a user asks about a specific game, the application: | |
| 1. Identifies the game being referenced | |
| 2. Retrieves game data from the Neo4j database | |
| 3. Displays a visual component with team logos, scores, and other game information | |
| 4. Generates a text summary in the chat | |
| Note: As mentioned in `docs/game_recap_implementation_instructions.md`, this component is still a work in progress. Currently, it displays above the chat window rather than embedded within chat messages. | |
| ## Security Considerations | |
| This repository includes: | |
| - `.gitignore` file to prevent committing sensitive information | |
| - `.env.example` files showing required environment variables without actual values | |
| - No hardcoded API keys or credentials in the code | |
| Before pushing to a public repository: | |
| 1. Ensure all sensitive information is in `.env` files (which are ignored by git) | |
| 2. Verify no API keys or credentials are hardcoded in any files | |
| 3. Check that large data files or binary files are properly ignored if needed | |
| ## Usage | |
| 1. Start the application | |
| 2. Ask questions about the 49ers, such as: | |
| - "Who are the current players on the 49ers roster?" | |
| - "Tell me about the 49ers game against the Chiefs" | |
| - "Which fan communities have the most members?" | |
| - "Show me the recap of the 49ers vs. Vikings game" | |
| The application will use the appropriate tools to answer your questions based on the data in the Neo4j database. | |
| ## Deployment | |
| This application has been deployed to HuggingFace Spaces and is publicly available at: | |
| [https://huggingface.co/spaces/aliss77777/ifx-sandbox](https://huggingface.co/spaces/aliss77777/ifx-sandbox) | |
| ### Deployment Steps | |
| 1. Used Gradio's built-in deployment feature: `gradio deploy --app-file gradio_app.py --title "49ers FanAI Hub"` | |
| 2. Uploaded environment variables securely as Secrets in the HuggingFace Space | |
| 3. Verified all API connections and data access on the deployed version | |
| The deployment process automatically handles: | |
| - Code upload to HuggingFace Spaces | |
| - Installing dependencies from requirements.txt | |
| - Building and serving the Gradio application | |
| ### Final Checks | |
| - Verified UI rendering and responsiveness | |
| - Confirmed data accuracy and Neo4j connection | |
| - Tested all features: chat, graph queries, and game recap functionality | |
| - Documented any deployment-specific issues or limitations | |