Wisdom Weaver

Wisdom Weaver is an AI agent designed to help non-data science experts extract essential insights from limited data. This project provides a framework for robust analysis, especially for small datasets, leveraging the capabilities of the Gemini CLI.

Overview

This project offers the following key functionalities:

• Small Data Modeling Strategy: In addition to traditional statistical models like linear regression, it explores and compares multiple modeling approaches, including physics-informed Ordinary Differential Equation (ODE) models and Bayesian models that explicitly handle uncertainty.
• Generic Model Comparison Framework: Implements a robust pipeline that allows for easy addition of new mathematical models and their comparison against existing ones.
• Automated Virtual Environment Management: Utilizes uv and venv to automatically manage project dependencies and execution environments, ensuring reproducibility.
• Interactive Analysis with Gemini CLI: The system is designed to be used interactively through the Gemini CLI, allowing users to guide the analysis process and receive metacognitive feedback.

Getting Started

Prerequisites

• Python 3.8+ installed.
• uv installed. If not installed, you can install it using:

  pip install uv

• Gemini CLI installed and configured. Follow the official Google Cloud documentation to install and set up the Gemini CLI. This typically involves:
  1. Installing the Google Cloud SDK.
  2. Installing the gcloud components install gemini component.
  3. Authenticating your gcloud account.

Installation and Setup

1. Clone the repository:

   git clone https://github.com/your-username/WisdomWeaver.git
   cd WisdomWeaver

2. Create Virtual Environment and Install Dependencies: Run run_model.bat (Windows) or run_model.sh (macOS/Linux) located in the project root directory. The first run will automatically create the virtual environment and install necessary dependencies.

   Windows:

   run_model.bat

   macOS / Linux:

   # Grant execute permission
   chmod +x run_model.sh
   # Run the script
   ./run_model.sh

   This will execute compare_models.py, performing comparison and evaluation of existing models.

Adding and Analyzing Models

This framework is designed to easily add new mathematical models and compare them.

1. BaseModel Interface

All mathematical models must inherit from the BaseModel abstract class defined in src/base_model.py. This requires models to implement the following methods:

• fit(self, X, y): Fits the model to data.
• predict(self, X): Performs predictions with the fitted model.
• evaluate(self, X, y): Evaluates the model and returns evaluation metrics (e.g., R2 score, MSE).

2. Creating New Models

Implement your new model class by inheriting from BaseModel and save it as a .py file in the models/ directory (for generic models) or user_models/ directory (for user-specific models).

Example: Using the Generic Ordinary Differential Equation (ODE) Model (GenericODEModel)

The GenericODEModel implemented in models/ode_model.py is a generic class that can numerically solve any differential equation and estimate its parameters from data.

To add a new differential equation model, follow these steps:

1. Define the differential equation function: Define a Python function in the format dy/dt = f(y, t, *params).

   • y: State variable (e.g., size, concentration)
   • t: Time
   • *params: Parameters to be estimated

   # Example: Model where dissolution rate is proportional to size
   def my_dissolution_ode(size, t, k):
       return -k * size

2. Instantiate GenericODEModel in compare_models.py: In the main function of compare_models.py, when instantiating GenericODEModel, pass your defined differential equation function and a list of names for the parameters to be estimated.

   from models.ode_model import GenericODEModel
   
   # ... (existing code)
   
   # Instantiate a new ODE model
   # You can add it directly to the all_models dictionary or ensure it's picked up by load_models_from_directory.
   # Currently, the instantiation of GenericODEModel in compare_models.py is hardcoded.
   # In the future, consider a mechanism to dynamically load user-defined ODE functions.
   
   # Example (if instantiating directly in compare_models.py):
   # if model_name == "GenericODEModel":
   #     model_instance = ModelClass(ode_function=my_dissolution_ode, param_names=['k'])

   Note: The current compare_models.py hardcodes the instantiation of GenericODEModel to a specific dissolution_ode_func. In the future, consider a mechanism to dynamically load and pass user-defined ODE functions to GenericODEModel for further generalization.

Adding Other Models

Refer to the implementations of the linear regression model (user_models/linear_regression_model.py) and the Bayesian model (models/bayesian_model.py) to add new statistical or machine learning models.

3. Running Models and Checking Results

After adding new models, run run_model.bat or run_model.sh again. This will compare all models, including the newly added ones, output results to the console, and save the plot to output/model_comparison.png.

Project Structure

WisdomWeaver/
├── .venv/                      # Python virtual environment (ignored by Git)
├── data/                       # Analysis data (ignored by Git)
├── output/                     # Generated analysis results, plots, etc. (ignored by Git)
├── user_models/                # User-created models (ignored by Git)
├── GEMINI.md                   # Internal guidelines for the AI agent's behavior
├── main.py                     # Main application entry point
├── metacognitive_analyst.md    # Defines the agent's "intellectual conscience" and pitfalls
├── README.md                   # This document
├── requirements.txt            # Project dependencies
├── run_model.bat               # Windows script to run models
├── run_model.sh                # macOS/Linux script to run models
├── src/                        # Source code
│   ├── agent.py                # Core agent logic
│   ├── base_model.py           # Abstract base class for all models
│   ├── phases.py               # Defines conversational phases
│   ├── socratic_guardrail.py   # Implements Socratic Guardrail logic
│   └── utils.py                # Utility functions
├── models/                     # Generic modeling implementations
│   ├── bayesian_model.py       # Bayesian modeling
│   └── ode_model.py            # Generic Ordinary Differential Equation modeling
└── tests/                      # Unit tests

License

Copyright (c) kadubon Licensed under the MIT License.
https://mit-license.org/