{"id":32929641,"url":"https://github.com/avnishchitrigi/agentic-time-series-analysis-reporting---forecasting","last_synced_at":"2026-05-16T15:36:14.705Z","repository":{"id":322994993,"uuid":"1091586782","full_name":"AvnishChitrigi/Agentic-Time-Series-Analysis-Reporting---Forecasting","owner":"AvnishChitrigi","description":"An interactive AI agent built with LangChain that automates end-to-end time series analysis and forecasting by collaborating with the user.","archived":false,"fork":false,"pushed_at":"2025-11-07T13:09:36.000Z","size":5202,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-07T14:28:35.497Z","etag":null,"topics":["ai-agent","automation","data-science","forecasting","generative-ai","google-gemini","human-in-the-loop","langchain","prompt-engineering","python","sarima","statsmodels","time-series"],"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/AvnishChitrigi.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":"2025-11-07T08:17:57.000Z","updated_at":"2025-11-07T13:09:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/AvnishChitrigi/Agentic-Time-Series-Analysis-Reporting---Forecasting","commit_stats":null,"previous_names":["avnishchitrigi/agentic-time-series-analysis-reporting---forecasting"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/AvnishChitrigi/Agentic-Time-Series-Analysis-Reporting---Forecasting","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AvnishChitrigi%2FAgentic-Time-Series-Analysis-Reporting---Forecasting","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AvnishChitrigi%2FAgentic-Time-Series-Analysis-Reporting---Forecasting/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AvnishChitrigi%2FAgentic-Time-Series-Analysis-Reporting---Forecasting/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AvnishChitrigi%2FAgentic-Time-Series-Analysis-Reporting---Forecasting/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AvnishChitrigi","download_url":"https://codeload.github.com/AvnishChitrigi/Agentic-Time-Series-Analysis-Reporting---Forecasting/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AvnishChitrigi%2FAgentic-Time-Series-Analysis-Reporting---Forecasting/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":283846898,"owners_count":26904663,"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","status":"online","status_checked_at":"2025-11-11T02:00:06.610Z","response_time":65,"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":["ai-agent","automation","data-science","forecasting","generative-ai","google-gemini","human-in-the-loop","langchain","prompt-engineering","python","sarima","statsmodels","time-series"],"created_at":"2025-11-11T12:01:33.831Z","updated_at":"2025-11-11T12:01:54.190Z","avatar_url":"https://github.com/AvnishChitrigi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Project Scribe: Interactive AI for Time Series Forecasting\n\nIt is an autonomous, interactive AI agent designed to perform end-to-end time series analysis and forecasting. It leverages a Large Language Model (LLM) as its core reasoning engine to replicate the entire workflow of a professional data scientist. The agent can inspect unfamiliar datasets, interact with the user to clarify goals, and then autonomously execute a robust statistical analysis pipeline, culminating in tailored reports for both technical and business audiences.\n\nThis project represents a paradigm shift from static automation scripts to dynamic, intelligent agents that can reason, act, and collaborate to solve complex analytical problems.\n\n## Core Features\n\n*   **Autonomous Operation:** Driven by the ReAct (Reason + Act) framework, the agent independently plans and executes a complex sequence of analytical tasks, from data discovery to final reporting.\n\n*   **Interactive \u0026 Collaborative (Human-in-the-Loop):** The agent is designed as a collaborative partner. It automatically scans for available datasets, identifies filterable columns, and then pauses its workflow to ask the user for guidance, making it practical for real-world, ambiguous data.\n\n*   **Dynamic Data Discovery:** The agent is not hard-coded for one dataset. It begins by exploring for unfamiliar CSV files, inspecting their structure, and dynamically adapting its entire analytical plan based on the user's choices.\n\n*   **Robust Statistical Engine:** The agent's \"toolbox\" grounds its reasoning in fact. It includes an automated grid search to programmatically find the optimal SARIMA model and an intelligent decomposition function that automatically determines the appropriate seasonal model.\n\n*   **Dual-Audience Reporting:** The agent synthesizes its findings into tailored technical and non-technical reports, effectively bridging the critical communication gap between data scientists and executive decision-makers.\n\n## GenAI Architecture\n\nThis project's intelligence is built on several key Generative AI methodologies, orchestrated by the LangChain framework.\n\n#### 1. The ReAct Framework (Reason + Act)\nThe agent operates on a continuous **Thought -\u003e Action -\u003e Observation** loop. This is the core of its autonomy. The LLM (Gemini 2.0 Flash) forms a plan (Thought), chooses a Python tool to execute (Action), and then receives a factual result from that tool (Observation) to inform its next thought.\n\n#### 2. Tool-Augmented Generation (Grounding)\nThe LLM is \"grounded\" in reality by a robust toolbox (`tools.py`). It cannot \"hallucinate\" a statistical result because it is forced to call a Python function that performs the real mathematical calculation. The `description` of each tool acts as the \"API documentation\" that the LLM reads to learn how to use its capabilities.\n\n#### 3. Advanced Prompt Engineering\nThe agent's \"programming\" is contained within the master prompt in `agent.py`. We use several techniques, including **Role-Prompting** (assigning an expert persona), **Chain of Thought** (providing a high-level methodology), and **Few-Shot Prompting** (providing a concrete example of a correctly formatted output) to ensure reliable and intelligent behavior.\n\n## Technology Stack\n\n| Component                  | Technologies                                                              |\n| -------------------------- | ------------------------------------------------------------------------- |\n| **Generative AI \u0026 Agents** | `langchain`, `langchain-google-genai` (for Google's Gemini 2.0 Flash) |\n| **Data Analysis \u0026 Stats**  | `pandas`, `numpy`, `statsmodels`, `scikit-learn`                            |\n| **Plotting \u0026 Visualization** | `matplotlib`, `seaborn`                                                   |\n| **Environment Management** | `python-dotenv`                                                           |\n\n## Project Structure\n\n```\nproject_scribe/\n├── .env                  # Stores the GOOGLE_API_KEY\n├── config.json           # Main configuration for paths\n├── main.py               # The main entry point to LAUNCH the agent\n├── README.md             # This file\n├── requirements.txt      # Python package dependencies\n|\n├── data/\n│   └── input/            # Place your CSV files here\n|\n├── outputs/\n│   ├── temp/             # Temporary storage for the prepared time series\n│   ├── logs/             # The final JSON analysis log\n│   ├── plots/            # All generated plots (.png)\n│   └── reports/          # Final text reports (.txt)\n|\n└── src/\n    └── scribe/\n        ├── agent.py      # The agent's \"brain\" and assembly\n        └── tools.py      # The agent's \"toolbox\" of Python functions\n```\n\n## Setup and Installation\n\nFollow these steps to get the project running.\n\n**1. Clone the Repository**\n```bash\ngit clone \u003cyour-repository-url\u003e\ncd project_scribe\n```\n\n**2. Create and Activate a Virtual Environment**\n```bash\n# For Windows\npython -m venv venv\nvenv\\Scripts\\activate\n\n# For macOS/Linux\npython3 -m venv venv\nsource venv/bin/activate\n```\n\n**3. Install Dependencies**\n```bash\npip install -r requirements.txt\n```\n\n**4. Set Up Your API Key**\nCreate a new file named `.env` in the root directory of the project. Add your Google AI Studio API key to this file.\n```\n# .env\nGOOGLE_API_KEY=\"your_api_key_here\"\n```\n\n**5. Add Your Data**\nPlace one or more CSV files into the `data/input/` directory.\n\n## How to Run\n\nAfter completing the setup, start the AI Analyst with a single command from the root directory:\n\n```bash\npython main.py\n```\nThe agent will begin its workflow. Be ready to provide input in the console when it asks you a question.\n\n## Future Work\n\n*   **Expand the Analytical Toolbox:**\n    *   Integrate additional forecasting models like **Prophet** and **Exponential Smoothing**.\n    *   Enable **SARIMAX** analysis by allowing the agent to identify and incorporate external regressors.\n    *   Add tools for **anomaly detection** to proactively flag unusual data points.\n\n*   **Enhance Agent Intelligence:**\n    *   **Rebuild with LangGraph:** Transition from a simple ReAct loop to a more robust state machine, enabling explicit error handling paths and more complex, cyclical reasoning.\n    *   **Implement Long-Term Memory:** Use a vector database to allow the agent to \"remember\" past analyses and apply learnings to new, similar datasets.\n\n*   **Improve User Experience:**\n    *   **Build a GUI:** Create a web-based front-end with **Streamlit** or **Gradio** to provide an interactive, user-friendly interface.\n    *   **Prototype with Langflow:** Use Langflow's visual, drag-and-drop canvas to rapidly prototype and visualize new agent architectures and workflows.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favnishchitrigi%2Fagentic-time-series-analysis-reporting---forecasting","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Favnishchitrigi%2Fagentic-time-series-analysis-reporting---forecasting","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favnishchitrigi%2Fagentic-time-series-analysis-reporting---forecasting/lists"}