📦 Inventra - AI Inventory and Financial Management

Inventra is an AI-powered multi-agent inventory and financial management system that enables natural-language interaction with business data. It uses a LangGraph orchestration layer to classify user intent, route queries to specialized report and decision agents, and generate context-grounded responses via Google Gemini.

🌐 Live Demo

Inventra Live

📑 Contents

• Features
• Architecture
• Quick Start
• Configuration
• Usage
• MCP Setup
• Project Structure
• Sample Queries
• Troubleshooting
• Tech Stack

✨ Features

• Multi-agent workflow using LangGraph.
• Natural-language inventory, sales, finance, ticket, and vendor queries.
• Gemini-powered business recommendations.
• Weather-aware demand planning through OpenWeatherMap.
• Auto-ticket generation on low-stock detection with traceable ticket IDs.
• Weather-adjusted budget impact analysis for financial queries.
• Structured output export (JSON/CSV) via MCP tool.
• RAG + Hybrid Search — Pinecone vector search + BM25 keyword search with Reciprocal Rank Fusion on vendor notes and climate advisories.
• SQLite database with schema and CSV seed data.
• Streamlit dashboard for chat, inventory exploration, tickets, and forecast accuracy.
• MCP server for Claude Desktop tool access (14 tools including export).
• MCP cross-system sync — Tickets can be routed to Jira, Notion, Slack via webhook.
• Conversation and forecast tracking.

🏗️ Architecture

Inventra follows a four-step agent flow: Classify → Gather → Decide → Respond.

For a complete architecture document with system diagrams, data flow sequences, component descriptions, and database schema, see ARCHITECTURE.md.

Main components:

• main.py starts the CLI, Streamlit UI, stats view, or database setup.
• agents/coordinator.py classifies queries and orchestrates the LangGraph workflow.
• agents/report_agent.py gathers inventory, sales, and finance summaries.
• agents/decision_agent.py generates AI-backed recommendations.
• services/ contains data pipeline, ticket, and forecast update logic.
• database/ contains SQLite helpers, schema, seed script, and sample data.
• mcp_server.py exposes Inventra tools to Claude Desktop over MCP.

🚀 Quick Start

git clone https://github.com/dhakksinesh/inventra.git
cd inventra

python -m venv venv

# Windows
venv\Scripts\activate

# macOS/Linux
source venv/bin/activate

pip install -r requirements.txt
cp .env.example .env

Edit .env with your API keys, then initialize the database:

python main.py setup

Run the web app:

python main.py web

The Streamlit UI opens at http://localhost:8501.

⚙️ Configuration

Create a .env file from .env.example:

cp .env.example .env

Values:

GEMINI_API_KEY=your_gemini_api_key_here
GEMINI_MODEL=gemini-2.5-flash
OPENWEATHER_API_KEY=your_openweather_api_key_here
OPENWEATHER_BASE_URL=https://api.openweathermap.org/data/2.5
PINECONE_API_KEY=your_pinecone_api_key_here
PINECONE_INDEX_NAME=inventra
PINECONE_EMBEDDING_MODEL=llama-text-embed-v2
PINECONE_EMBEDDING_DIM=1024
DATABASE_PATH=./database/inventra.db
LOG_LEVEL=INFO
WEATHER_CACHE_TTL=1800
MAX_CONVERSATION_HISTORY=10
WEBHOOK_URL=your_webhook_url_here

🖥️ Usage

Start the Streamlit app:

python main.py web

Start the interactive CLI:

python main.py cli

Show system statistics:

python main.py stats

Rebuild and seed the SQLite database:

python main.py setup

🔌 MCP Setup

Inventra includes an MCP server for Claude Desktop:

python mcp_server.py

Claude Desktop should be configured to run mcp_server.py from this project using the Python environment where requirements.txt was installed.

Example claude_desktop_config.json entry:

{
  "mcpServers": {
    "inventra": {
      "command": "python",
      "args": [
        "C:/absolute/path/to/inventra/mcp_server.py"
      ],
      "env": {
        "GEMINI_API_KEY": "your_gemini_api_key_here",
        "OPENWEATHER_API_KEY": "your_openweather_key_here"
      }
    }
  }
}

Full instructions are in MCP_SETUP.md.

📁 Project Structure

Click to expand full project structure

inventra/
|-- agents/
|   |-- __init__.py
|   |-- coordinator.py          # LangGraph workflow orchestration
|   |-- decision_agent.py       # AI-powered business recommendations
|   |-- report_agent.py         # Inventory, sales, finance data retrieval
|
|-- config/
|   |-- __init__.py
|   |-- settings.py             # Pydantic settings from .env
|   |-- logger.py               # Logging configuration
|
|-- database/
|   |-- __init__.py
|   |-- inventra.db             # Pre-seeded SQLite database
|   |-- schema.sql              # Database schema definition
|   |-- db_manager.py           # SQLite connection, query, execute helpers
|   |-- db_queries.py           # Shared queries (circular import breaker)
|   |-- memory_manager.py       # Conversation history, forecast tracking
|   |-- seed_db.py              # Database seeding script
|   |-- data/                   # Seed CSV source files
|       |-- finance.csv
|       |-- inventory.csv
|       |-- sales.csv
|       |-- vendors.csv
|
|-- services/
|   |-- __init__.py
|   |-- data_pipeline.py        # Sales analysis, vendor performance, weather impact
|   |-- ticket_manager.py       # Ticket CRUD, auto-generation, webhook sync
|   |-- forecast_updater.py     # Forecast accuracy tracking and updates
|   |-- vector_store.py         # Pinecone embeddings + BM25 hybrid search with RRF
|
|-- tools/
|   |-- finance.py              # Financial calculations and summaries
|   |-- weather.py              # OpenWeatherMap API integration
|
|-- ui/
|   |-- __init__.py
|   |-- streamlit_app.py        # Main Streamlit dashboard
|
|-- main.py                     # CLI entry point (web/cli/stats/setup)
|-- mcp_server.py               # MCP server for Claude Desktop
|-- requirements.txt            # Python dependencies
|-- .env.example                # Template for .env
|-- ARCHITECTURE.md             # Detailed architecture document
|-- MCP_SETUP.md                 # Claude Desktop MCP setup
`-- README.md

💬 Sample Queries

Show me the financial summary
What items are low in stock?
Check inventory for North region
Which products need reordering?
Give me reorder recommendations
Suggest vendors for restocking
Analyze sales opportunities
Show pending tickets
What should I stock for monsoon season?

🔧 Troubleshooting

API key errors

Check that .env exists in the project root and contains valid values for GEMINI_API_KEY and OPENWEATHER_API_KEY.

Database not found

Run:

python main.py setup

Import errors

Activate your virtual environment and reinstall dependencies:

pip install -r requirements.txt

Claude Desktop does not show Inventra tools

Check the absolute path to mcp_server.py in claude_desktop_config.json, confirm that mcp is installed, and restart Claude Desktop.

🛠️ Tech Stack

Component	Technology
LLM	Google Gemini
Database	SQLite
Vector DB	Pinecone (Serverless)
Embeddings	llama-text-embed-v2
Keyword Search	BM25 (in-memory index)
Score Fusion	Reciprocal Rank Fusion
Orchestration	LangGraph
LLM Framework	LangChain
UI Framework	Streamlit
Numerical	NumPy
Weather Data	OpenWeatherMap API
MCP Integration	MCP Python SDK
Data Analytics	Pandas
Data Validation	Pydantic / Pydantic-settings
Backend	Python 3.12+