{"id":14981059,"url":"https://github.com/williamzebrowski/assistant-api","last_synced_at":"2026-02-16T14:32:49.944Z","repository":{"id":255201282,"uuid":"821556844","full_name":"williamzebrowskI/assistant-api","owner":"williamzebrowskI","description":"OpenAI Assistant API integrated with Elasticsearch, Logstash \u0026 Kibana","archived":false,"fork":false,"pushed_at":"2024-09-03T18:40:27.000Z","size":2120,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-08T01:56:06.700Z","etag":null,"topics":["ai","chatapp","chatgpt","conversational-ai","data","elasticsearch","kibana","llm-inference","llms","openai","rag"],"latest_commit_sha":null,"homepage":"","language":"Python","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/williamzebrowskI.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":["williamzebrowskI"]}},"created_at":"2024-06-28T20:19:12.000Z","updated_at":"2024-09-04T00:36:19.000Z","dependencies_parsed_at":"2024-08-28T15:37:31.281Z","dependency_job_id":"3c2e9834-5e3b-4606-b5e7-71e9abeecf69","html_url":"https://github.com/williamzebrowskI/assistant-api","commit_stats":{"total_commits":181,"total_committers":2,"mean_commits":90.5,"dds":0.06077348066298338,"last_synced_commit":"c4ce613df06ad922a11b85c5738d7aa21c2d4824"},"previous_names":["williamzebrowski/assistant-api"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamzebrowskI%2Fassistant-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamzebrowskI%2Fassistant-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamzebrowskI%2Fassistant-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamzebrowskI%2Fassistant-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/williamzebrowskI","download_url":"https://codeload.github.com/williamzebrowskI/assistant-api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238768422,"owners_count":19527197,"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":["ai","chatapp","chatgpt","conversational-ai","data","elasticsearch","kibana","llm-inference","llms","openai","rag"],"created_at":"2024-09-24T14:02:48.470Z","updated_at":"2025-09-23T20:58:20.432Z","avatar_url":"https://github.com/williamzebrowskI.png","language":"Python","funding_links":["https://github.com/sponsors/williamzebrowskI"],"categories":[],"sub_categories":[],"readme":"\u003cdiv style=\"text-align: center; padding: 20px; background-color: #333;\"\u003e\n    \u003ch1 style=\"font-family: 'Arial', sans-serif; color: #FFFFFF; font-size: 2.5em; margin: 20px 0;\"\u003eAssistant-API\u003c/h1\u003e\n    \u003ch2 style=\"font-family: 'Arial', sans-serif; color: #FFFFFF; font-size: 1.75em; margin-bottom: 20px; font-style: italic;\"\u003e\n        w/ Elasticsearch, Logstash + Kibana (ELK Stack)\n    \u003c/h2\u003e\n\u003c/div\u003e\n\n![GitHub stars](https://img.shields.io/github/stars/williamzebrowski/assistant-api)\n![GitHub forks](https://img.shields.io/github/forks/williamzebrowski/assistant-api)\n![GitHub watchers](https://img.shields.io/github/watchers/williamzebrowski/assistant-api)\n![GitHub repo size](https://img.shields.io/github/repo-size/williamzebrowski/assistant-api)\n![GitHub language count](https://img.shields.io/github/languages/count/williamzebrowski/assistant-api)\n![GitHub top language](https://img.shields.io/github/languages/top/williamzebrowski/assistant-api)\n![GitHub last commit](https://img.shields.io/github/last-commit/williamzebrowski/assistant-api)\n![Hits](https://hits.seeyoufarm.com/api/count/incr/badge.svg?url=https://github.com/williamzebrowski/assistant-api)\n\nWelcome to the `assistant-api` package, which includes the AssistantsAPI backend designed to streamline inquiries through a chat widget. This application combines the capabilities of OpenAI’s Assistants with Elasticsearch (for data storage), Logstash (for real-time data processing and transformation), and Kibana (for data visualization) to create an intuitive and efficient system for conversational storage, management, and visualization.\n\nThis infrastructure allows users to connect to an Assistant on OpenAI, interact with it, and store conversational data in an Elasticsearch index for future reference and analysis. Logstash processes and enriches the incoming data before storing it, ensuring that the data is clean, structured, and ready for advanced analysis. With Kibana, users can visualize and explore the stored data. This combination ensures comprehensive observability and data-driven insights across all aspects of the application.\n\n## Table of Contents\n- [Diagram Depiction](#diagram-depiction)\n- [Getting Started](#getting-started)\n  - [Prerequisites](#prerequisites)\n  - [Setting Up a Virtual Environment](#setting-up-a-virtual-environment)\n  - [Configuration](#configuration)\n  - [Running the Application](#running-the-application)\n- [Startup](#startup)\n  - [Running with Docker](#running-with-docker)\n  - [Running without Docker](#running-without-docker)\n- [Running from Docker Hub](#running-from-docker-hub)\n- [Assistant API Overview](#assistant-api-overview)\n- [Key Components](#key-components)\n  - [FastAPI Setup](#fastapi-setup)\n  - [OpenAI Integration](#openai-integration)\n  - [Elasticsearch Connector](#elasticsearch-connector)\n  - [Conversational Flow](#conversational-flow)\n- [Running the Assistant](#running-the-assistant)\n- [Environment Configuration](#environment-configuration)\n- [Logging and Debugging](#logging-and-debugging)\n\n\u003c!-- The following Diagram depicts the flow of a user's message from end to end.\n![Assistant API Diagram](images/flow.png) --\u003e\n\n## Getting Started\n\n### Prerequisites\n\n- Python 3.11\n- pip\n- Poetry\n\n### Setting Up a Virtual Environment\n\n1. **Clone this repository:**\n    ```bash\n    git clone https://github.com/williamzebrowskI/assistant-api.git\n    cd assistant-api\n    ```\n\n2. **Create a `.env` File**:\n    Create a `.env` file in the root of your project and fill it with your OpenAI and Elasticsearch credentials:\n\n    ```\n    OPENAI_API_KEY=your_openai_api_key_here\n    ASSISTANT_ID=your_assistants_id_here\n\n    # Elasticsearch cloud authentication credentials\n    ELASTIC_VERSION=8.15.0\n    ES_URL=https://localhost\n    ES_PORT=9200\n    ES_INDEX=ai-index\n    ES_USERNAME=elastic\n\n    ELASTIC_PASSWORD='changeme'\n    KIBANA_SYSTEM_PASSWORD='changeme'\n    LOGSTASH_INTERNAL_PASSWORD='changeme'\n    \n    CORS_ALLOWED_ORIGINS=\"http://127.0.0.1:8002\"\n    ```\n\n    Ensure you replace the placeholder values with your actual credentials.\n\n## Startup\n\n### Running with Docker Compose\n\n1. **Start the Docker Containers**:\n    ```bash\n    docker-compose up --build\n    ```\n\n2. **Accessing the Chat Interface:**\n    Once the server is up and running, a link is provided in the logs directed to the chat widget, http://localhost:8001.\n\n3. **Accessing Kibana:**\n    Once Kibana is fully up and running, you can access it by navigating to [http://localhost:5601](http://localhost:5601) in your web browser. Kibana provides a powerful UI for visualizing and managing data in Elasticsearch. You can create dashboards, explore the data stored in your Elasticsearch indices, and set up alerts.\n\n    To get into Kibana, the `username` and `password` will be printed after. ie:\n\n    ```sh\n    username: elastic\n    password: \u003cgenerated password\u003e\n    ```\n\n\n### Running without Docker\n\n1. **Clone the Repository**\n    ```bash\n    git clone https://github.com/williamzebrowskI/assistant-api.git\n    cd assistant-api\n    ```\n\n2. **Create and Activate a Virtual Environment**\n    ```bash\n    python -m venv venv\n    source venv/bin/activate  # On Windows use `venv\\Scripts\\activate`\n    ```\n\n3. **Install Dependencies**\n    ```bash\n    pip install poetry\n    poetry install\n    ```\n\n4. **Set Up Environment Variables**\n    Create a `.env` file in the root of your project and fill it with your OpenAI and Elasticsearch credentials:\n    ```plaintext\n    OPENAI_API_KEY=your_openai_api_key_here\n    ASSISTANT_ID=your_assistants_id_here\n    # Elasticsearch cloud authentication credentials\n    ELASTIC_VERSION=8.15.0\n    ES_URL=https://localhost\n    ES_PORT=9200\n    ES_INDEX=ai-index\n    ES_USERNAME=elastic\n    CORS_ALLOWED_ORIGINS=\"http://127.0.0.1:8002\"\n    ELASTIC_PASSWORD='changeme'\n    KIBANA_SYSTEM_PASSWORD='changeme'\n    LOGSTASH_INTERNAL_PASSWORD='changeme'\n    ```\n\n5. **Run the Application**\n    ```bash\n    poetry run gunicorn --config app/ws/gunicorn_config.py --worker-class eventlet -w 1 app.main:app_instance -b 0.0.0.0:8002\n    ```\n\n### Running from Docker Hub\n\nTo make it easier for users to install and run the application, you can pull and run the Docker image directly from Docker Hub.\n\n1. **Run the Docker Container**:\n\n    ```bash\n    docker run -d -p 8001:8001 -p 8002:8002 --name assistant-api --restart always \\\n        -e FE_PORT=8001 \\\n        -e ES_HOST=elasticsearch \\\n        -e ES_PORT=9200 \\\n        -e ES_INDEX=ai-index \\\n        -e ES_USERNAME=elastic \\\n        -e ES_PASSWORD_FILE=/app/es_config/es_output.txt \\\n        -e OPENAI_API_KEY=your_openai_api_key_here \\\n        -e ASSISTANT_ID=your_assistants_id_here \\\n        -v shared_data:/app/es_config \\\n        wzebrowski/assistant-api:\u003cversion number\u003e\n    ```\n\n## Assistant API Overview\n\nThe Assistant API is designed to facilitate interactions with users seeking guidance or information via a ChatGPT-powered conversational interface. This assistant leverages the OpenAI API for generating responses and Elasticsearch for logging and retrieving conversation histories.\n\n## Key Components\n\n### FastAPI Setup\n\n- **FastAPI Application**: Initiates a FastAPI server, enabling HTTP requests handling for the chat interface.\n- **CORS Middleware**: Configures Cross-Origin Resource Sharing (CORS) settings to allow web requests from different origins, ensuring the frontend can communicate with the backend.\n\n### OpenAI Assistant Integration\n\n#### OpenAIAssistant Class Overview\n\nThe `OpenAIAssistant` class is designed to seamlessly integrate OpenAI's GPT models into our application, enabling the generation of dynamic, intelligent responses to user queries. This integration is pivotal for facilitating an engaging conversational experience in the Assistant API application.\n\n##### Purpose\n\nThe primary purpose of the `OpenAIAssistant` class is to abstract the complexities involved in communicating with the OpenAI API. It manages the lifecycle of conversations, including initiating new threads, managing ongoing conversations, and generating responses based on user input.\n\n##### Setup\n\nTo utilize the `OpenAIAssistant`, ensure you have the following configured:\n\n- **API Key**: Securely store the OpenAI API key in your environment variables or `.env` file. This key is required to authenticate your requests to the OpenAI API.\n- **Assistant Configuration**: Define the specific GPT model (e.g., `gpt-3.5-turbo`) and settings appropriate for your application's conversational needs.\n\n##### Key Functionalities\n\n###### `initialize_conversation()`\n\n- Initializes a new conversation thread with OpenAI, setting up the context and parameters for the conversation.\n- Stores conversation state to facilitate seamless continuation of the conversation.\n\n###### `generate_response(user_query)`\n\n- Sends the user's query to OpenAI and retrieves a response based on the current conversation context.\n- Utilizes advanced natural language processing and generation techniques to ensure the response is relevant, accurate, and coherent.\n\n###### `manage_conversation_state()`\n\n- Dynamically manages the conversation's state, including tracking the conversation history and context changes.\n- Ensures that each response is contextually appropriate, maintaining a natural and logical flow to the conversation.\n\n#### Integration Benefits\n\nIntegrating the `OpenAIAssistant` class into our application brings several key benefits:\n\n- **Enhanced User Experience**: By leveraging OpenAI's advanced NLP capabilities, the assistant can provide users with highly relevant, informative, and engaging responses.\n- **Scalability**: The modular design of the `OpenAIAssistant` allows for easy updates and modifications, such as changing the GPT model or adjusting conversation parameters, without extensive code overhauls.\n- **Simplicity**: The abstraction provided by the class simplifies the process of integrating complex AI functionalities into the application, making the development process more efficient and less error-prone.\n\n##### Conclusion\n\nThe `OpenAIAssistant` class represents a core component of our Assistant API application, bridging the gap between user queries and the sophisticated language understanding and generation capabilities of OpenAI's GPT models. Through this integration, we aim to deliver an exceptional conversational experience that aids users in navigating their inquiries.\n\n# Elasticsearch Connector\n\n## Elastic Data Model Integration\n\nThis documentation outlines the setup and usage of the Elastic Data Model within our AssistantAPI application. Our model leverages Elasticsearch for operations such as document creation, updates, and management within an Elasticsearch index. The integration is facilitated through the `ElasticConnector` class, which establishes a connection to Elasticsearch using environmental variables and provides asynchronous methods for interacting with the data.\n\n## Setup\n\n### Environment Variables\n\nBefore utilizing the `ElasticConnector`, ensure the following environmental variables are set in your environment or within a `.env` file:\n\n- `ES_URL`: The URL of your Elasticsearch instance.\n- `ES_INDEX`: The Elasticsearch index to which documents will be pushed and from which they will be retrieved.\n- `ES_PORT`: The port on which your Elasticsearch instance is running.\n\nThese variables are critical for establishing a connection to Elasticsearch. The connector will log warnings if any of these are unset.\n\n## ElasticConnector Class\n\n### Initialization\n\nUpon instantiation, the `ElasticConnector` class initializes a connection to an Elasticsearch instance using the aforementioned environmental variables. This connection is essential for performing asynchronous operations against the Elasticsearch index.\n\n### Methods\n\n#### async push_to_index(conversation_uuid, user_id, thread_id, assistant_id)\n\nThis asynchronous method creates a new conversation document in Elasticsearch. The document includes metadata such as the user's ID, the client's IP address, the thread's ID, the assistant's ID, and a timestamp marking the creation time. This setup initializes an empty list for conversations to hold future interactions.\n\n**Parameters:**\n\n- `conversation_uuid` (str): Unique identifier for the conversation document.\n- `user_id` (str): ID of the user initiating the conversation.\n- `thread_id` (str): Unique identifier of the thread associated with the conversation.\n- `assistant_id` (str): ID of the assistant involved in the conversation.\n\n#### async update_document(conversation_uuid, user_query, assistant_response)\n\nThis method appends a new interaction to the conversations array of an existing document. Each interaction consists of a user query and the corresponding assistant response, allowing for the historical tracking of interactions within a conversation.\n\n**Parameters:**\n\n- `conversation_uuid` (str): Unique identifier for the conversation document.\n- `user_query` (str): The query submitted by the user.\n- `assistant_response` (str): The response generated by the assistant.\n\nBoth methods handle exceptions gracefully by logging errors, ensuring the application's stability in the face of Elasticsearch operation failures.\n\n## Conclusion\n\nThe `ElasticConnector` class provides a streamlined approach to integrating Elasticsearch into your application for handling conversation data. By following the setup instructions and utilizing the provided methods, you can efficiently manage conversation documents within your chosen Elasticsearch index.\n\n### Conversational Flow\n\n1. **Client-Side Identification**: When the user starts a conversation, a `conversation_uuid` and `user_id` are generated to uniquely identify the session and user across interactions.\n   \n2. **Thread Creation**: Initiates a new conversation thread for first-time queries or appends messages to existing threads using the `thread_id`.\n   \n3. **Message Handling**: Manages the exchange of messages between the user and the OpenAI Assistant, maintaining the context and continuity of the conversation.\n   \n4. **Elasticsearch Logging**: Archives each conversation in Elasticsearch, tagging them with `conversation_uuid` and `user_id` to construct a detailed history for analysis and continued dialogue.\n\n### Running the Assistant\n\n- Execute `python app.py` to start the FastAPI server.\n- Access the chat interface through the provided HTML frontend to interact with the assistant.\n\n## Environment Configuration\n\nIncludes a `.env` file setup for securely managing API keys and Elasticsearch connection details, crucial for operational integrity and data security.\n\n## Logging and Debugging\n\nUtilizes Python's logging module to track application events, aiding in monitoring and troubleshooting.\n\n---\n\nThis assistant exemplifies a modern approach to building conversational AI applications, emphasizing modularity, scalability, and ease of integration with advanced NLP models and database technologies.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwilliamzebrowski%2Fassistant-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwilliamzebrowski%2Fassistant-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwilliamzebrowski%2Fassistant-api/lists"}