Skip to content
BranchesTags

Repository files navigation

ArgoFloat

AI-powered conversational tooling for exploring Argo oceanographic data. This project combines MCP (Model Context Protocol) tools for querying the Argovis API with a lightweight RAG stack over local documentation to help users ask natural-language questions.

Features

✅ Implemented

  • MCP Server: FastMCP server with tools for nearest_floats, time_series, profile_summary, salinity_equator, etc.
  • RAG Pipeline: Chroma vector store with Google Gemini embeddings for documentation
  • Streamlit Dashboard: Multi-page web interface
    • 📥 Ingest: Index docs and ingest NetCDF files to Parquet/DuckDB/Chroma
    • 🧭 Explore: Find floats, equatorial salinity, time series
    • 📊 Visualize: Depth-time plots, profile comparisons
    • 💬 Chat: Agent with MCP tools for comprehensive answers
  • Data Pipeline: NetCDF → Parquet → DuckDB → Chroma indexing
  • Interactive Visualizations: Plotly-based depth-time plots and profile comparisons

🚧 In Progress

  • Sample data ingestion and testing
  • Performance optimizations

Quick Start

Prerequisites

  • Python 3.13+
  • uv package manager
  • Google AI API key

Setup

  1. Clone and install dependencies:
git clone <repository>
cd argofloat
uv sync
  1. Configure environment:
cp .env.example .env
# Edit .env with your GOOGLE_API_KEY
  1. Run system test:
uv run python test_system.py
  1. Start the dashboard:
uv run streamlit run streamlit_app.py

Architecture

Data Flow

NetCDF Files → xarray → DataFrame → Parquet (partitioned) → DuckDB Views → Chroma (profiles)

Components

  • argo_ingest.py: NetCDF parsing, Parquet storage, DuckDB views, Chroma indexing
  • argo_data_query.py: Query interface with caching
  • argo_mcp/server.py: MCP tools for Argovis API
  • argo_rag/: Documentation RAG pipeline
  • pages/: Streamlit dashboard pages
    • 1_📥_Ingest.py: Data ingestion interface
    • 2_🧭_Explore.py: Data exploration tools
    • 3_📊_Visualize.py: Data visualization
    • 4_💬_Chat.py: AI chat interface with RAG + MCP tools
    • 5_📚_Chroma_DB.py: Chroma DB visualizer for vector database exploration

Tools Available

  • search_docs: Semantic search over ARGO documentation
  • nearest_floats: Find ARGO floats near a location
  • time_series: Get time series data for variables
  • profile_summary: Statistics for specific profiles
  • salinity_equator: Salinity profiles near equator

Usage Examples

Ingest Data

  1. Place NetCDF files in ./data/netcdf/
  2. Go to Ingest page → Enter directory path → Click "Ingest NetCDF"

Ask Questions

  • "Find ARGO floats near 0°N, 0°E"
  • "Show salinity time series for platform 5905107"
  • "Compare temperature profiles between these two floats"
  • "What are BGC parameters in the Arabian Sea?"

Visualize Chroma DB

Go to the Chroma DB Visualizer page to:

  • Explore your vectorized ARGO documentation

  • View document statistics and distributions

  • Search through indexed content

  • Analyze metadata patterns

  • Monitor collection health

  • Depth-time plots (Hovmöller diagrams)

  • Profile comparisons with QC masking

  • Interactive time series

Environment Variables

  • GOOGLE_API_KEY: Required for Gemini embeddings and chat
  • ARGOVIS_API_KEY: Optional (defaults to "guest")
  • ARGOVIS_API_ROOT: Optional (defaults to Argovis API URL)

Development

Run Tests

uv run python test_system.py

Add Dependencies

uv add package_name

Update Documentation

# Index docs to Chroma
uv run python -c "from argo_rag.indexer import create_vectorstore; create_vectorstore('./docs')"

Datasets:

Organization: Ministry of Earth Sciences (MoES), INCOIS

What’s in this repo

  • MCP server for Argo tooling (Argovis-backed)
    • File: argo_mcp/server.py
    • Tools (selection):
      • salinity_equator: salinity profiles near equator for a given month/year
      • compare_bgc: recent BGC variable statistics over a named region
      • nearest_floats: nearest float platforms to a lat/lon
      • search_docs: semantic search over local RAG index (Argovis docs)
      • time_series: aggregated variable per profile over time
      • section_extraction: along-track transects with depth interpolation
      • climatology_lookup: RG09 monthly climatology comparison
      • profile_summary: stats for variables in a single profile
  • Lightweight RAG over local docs
  • Entry point script
  • Streamlit dashboard
  • Project config and lockfiles

Development setup

Commands:

  • Install deps: uv sync
  • Run a script: uv run python <script.py>
  • Add a dependency: uv add <package>
  • Run this project: uv run python main.py

Important: DO NOT EDIT pyproject.toml. Use uv for all dependency operations.

Environment variables

  • ARGOVIS_API_KEY (optional; defaults to “guest”)
  • ARGOVIS_API_ROOT (optional; defaults to https://argovis-api.colorado.edu)
  • GOOGLE_API_KEY (required for Google Generative AI embeddings in RAG)

Export on Linux/macOS:

export ARGOVIS_API_KEY="your_key"
export GOOGLE_API_KEY="your_google_api_key"

Quickstart

  1. Install
uv sync
  1. Build a local vector store from docs (Chroma persisted to ./chroma_db)
uv run python indexer.py
  • This loads docs/, splits text, embeds with Gemini (langchain-google-genai), and persists into Chroma.
  1. Run the MCP server (inspector/dev)
uv run mcp dev argo_mcp/server.py
  • Use the MCP Inspector to invoke tools like salinity_equator, nearest_floats, or search_docs.
  • The server will use ArgoRetriever when available to serve search_docs.
  1. Minimal run
uv run python main.py
  1. Launch the Streamlit dashboard
uv run streamlit run streamlit_app.py
  • This starts the interactive web dashboard for data visualization and exploration.

Key components

  • MCP server: argo_mcp/server.py
    • Uses mcp.server.fastmcp.FastMCP and exposes tools/resources for Argovis and local RAG.
    • Respects ARGOVIS_API_KEY and ARGOVIS_API_ROOT.
    • Performs safe HTTP requests via httpx with structured error handling.
    • Example routes used: /argo, /argo/meta, /argo/vocabulary.
  • RAG
    • Indexer: indexer.py creates Chroma embeddings with GoogleGenerativeAIEmbeddings.
    • Retriever: ArgoRetriever provides similarity_search and similarity_search_with_score.

Docs you can query:

Streamlit Dashboard

  • Interactive web interface: streamlit_app.py
    • Built with Streamlit for user-friendly data exploration
    • Chat Assistant: AI-powered chatbot using LangChain and Gemini for natural language queries
    • Planned features: maps, charts, profile comparisons, and data export
    • Run with: uv run streamlit run streamlit_app.py

Example MCP usage hints

  • List available vocabulary categories:
    • Resource: resource://argovis/vocabulary
  • Fetch a specific vocabulary category:
    • Resource: resource://argovis/vocabulary/{category}
  • Find salinity near the equator for a month:
    • Tool: salinity_equator(year, month, lat_band=5.0, limit=50)
  • Search local docs:
    • Tool: search_docs(query="...") (requires the Chroma index)

See the tool definitions in argo_mcp/server.py.

Roadmap (Expected Solution alignment)

  • Ingestion/ETL
    • Parse Argo NetCDF → Parquet/SQL schemas (PostgreSQL), with metadata summaries for RAG.
  • Vector DB
    • Enrich vector index with platform/profile summaries; support FAISS/Chroma backends.
  • LLM + RAG + MCP
    • Natural-language → SQL mapping for structured queries.
    • Grounded answers with citations and profile links.
  • Frontend
    • Streamlit/Dash dashboards: maps (Leaflet/Plotly), depth–time sections, profile comparisons.
    • Export views and subsets to ASCII/NetCDF.
  • Chat experience
    • Intent classification, guided refinement (already used in tools via elicitation), and multi-turn drilling.
  • PoC focus
    • Indian Ocean subset first; extend to BGC/gliders/buoys/satellite products.

Contributing

  • Use uv add <package> to add dependencies.
  • Prefer small, focused PRs.
  • Keep simple script logic in main.py; grow modules under argo_* packages.

Troubleshooting

  • No doc search results:
    • Ensure you ran uv run python indexer.py and set GOOGLE_API_KEY.
  • Argovis requests failing:
    • Set a valid ARGOVIS_API_KEY and check network access.
  • ChromaDB connection issues:
    • The visualizer tries multiple connection methods automatically
    • If "already exists with different settings" error occurs, use "Force reset database"
    • Check directory permissions: ls -la chroma_db/
    • Kill conflicting processes: pkill -f chromadb
  • MCP inspector cannot find tools:
    • Verify uv run mcp dev argo_mcp/server.py and check console logs.

License

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages