WIA — Workspace Intelligence Agent

Workspace Intelligence Agent (WIA) is a high-performance, graph-grounded workspace intelligence platform and codebase reasoning engine. It builds a deep, structured understanding of software repositories by parsing Abstract Syntax Trees (AST), building entity relationship graphs, processing Jupyter notebooks, and grounding AI reasoning in verified codebase evidence.

Repository
    ↓
Files & Jupyter Notebooks
    ↓
Source AST & Structural Tokens
    ↓
Inverted Search Index & Symbol Graph
    ↓
Architectural Subsystem & Boundary Discovery
    ↓
WorkspaceRetriever & Dynamic Context Budgeting (7,500 Tokens)
    ↓
AI Reasoning Engine (NVIDIA NIM / OpenAI / Claude / Local)
    ↓
Grounded, Citation-Backed Structured Response

⚡ Key Highlights & Core Capabilities

1. Evidence-Grounded AI Reasoning (Zero-Hallucination): Every answer is derived strictly from verified workspace source files, AST symbols, imports, call graphs, tests, and configuration manifests.
2. High-Performance Inverted Search Index ($O(1)$ Symbol Lookup): Sub-millisecond token and symbol resolution across codebases with thousands of files and tens of thousands of symbols.
3. Massive 7,500-Token LLM Context Budget: Expanded retrieval budget with adaptive context reduction and retry for remote models with tight TPM/RPM quotas.
4. Response Relevance Grader & Structured Formatting: Validates responses for query relevance (0–100%), verified grounding citations, and consistent section breakdowns.
5. Multi-Language AST & Structural Parser: Deep parsing for Python (ast), plus multi-language regex fallback for TypeScript/JavaScript, Go, Rust, Java, C#, and C++.
6. Jupyter Notebook (.ipynb) Understanding: Full cell-level parsing (markdown hierarchy, code AST symbols, execution flow, output summaries) rather than opaque classification.
7. High-Speed Relational Persistence: SQLite persistence layer using atomic executemany batch operations and relational indices for instant queries.
8. $O(1)$ Workspace Knowledge Graph: Maintains directional dependency edges (IMPORTS, DEFINES, CALLS, INHERITS, TESTS) with $O(1)$ edge management.
9. Multi-Tier Blast Radius & Impact Analysis: Inspects direct callers, transitive dependents, affected unit tests, and dependent workflows before refactoring.
10. Zero-Credential PyPI Package: 100% credential-safe. API keys are masked in logs and outputs. Deterministic commands run 100% offline without API keys.

🚀 Installation & Quickstart

PyPI Installation

# Install WIA distribution from PyPI
pip install wia-agent

# Verify CLI installation
wia --version
wia doctor

# Or execute directly via Python module
python -m wia --version

Local Development Setup

# 1. Clone repository
git clone https://github.com/Yashwanth112004/Workspace-Intelligence-Agent.git
cd Workspace-Intelligence-Agent

# 2. Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# 3. Install in editable mode with development dependencies
pip install -e ".[dev]"

# 4. Run automated test suite
pytest

⚙️ AI Provider Configuration

Deterministic commands (wia index, wia status, wia summary, wia search, wia explain, wia impact, wia architecture, wia flow, wia diff) run completely offline.

To enable AI reasoning for wia ask:

# Option A: Set via Environment Variable
export NVIDIA_API_KEY="nvapi-..."
# or for OpenAI: export OPENAI_API_KEY="sk-..."

# Option B: Set via WIA Configuration CLI
wia config --set-key "nvapi-..."
wia config --set-provider nvidia
wia config --set-model meta/llama-3.1-70b-instruct

# View active configuration
wia config --show

🛠️ Complete CLI Command Reference

🏗️ Architectural Flow & Subsystem Breakdown

               WIA CLI Dispatcher (`wia/cli`)
                             │
                  Intent Classification & Routing
                             │
        ┌────────────────────┴────────────────────┐
        │                                         │
Deterministic Engine                      Reasoning Engine (`wia/llm`)
        │                                         │
 ┌──────┴──────────────────────────┐       ┌──────┴──────────────────────────┐
 │ IndexingService & DiscoveryPool │       │ WorkspaceRetriever              │
 │ InvertedSearchIndex (O(1))      │       │ Dynamic Context (7,500 Tokens)  │
 │ ASTParser & NotebookParser      │       │ ResponseRelevanceGrader         │
 │ SQLiteStore (executemany)       │       │ AIProvider Layer                │
 │ WorkspaceGraph (O(1) Edges)     │       │  ├─ NvidiaNimProvider           │
 │ ManifestParser (Single Walk)    │       │  ├─ OpenAIProvider              │
 │ SecretScanner & GitAnalyzer     │       │  └─ LocalReasoningProvider      │
 └─────────────────────────────────┘       └─────────────────────────────────┘

📁 Repository Structure

Workspace-Intelligence-Agent/
├── wia/
│   ├── analyzers/
│   │   ├── code/                  # AST parser & Jupyter notebook parser
│   │   ├── dependency/            # Single-pass manifest parser & conflict detector
│   │   ├── git/                   # Git commit churn and hotspot analyzer
│   │   └── security/              # High-throughput secret & credential scanner
│   ├── cli/
│   │   ├── app.py                 # Lazy CLI dispatcher
│   │   ├── formatting.py          # Terminal styling & table formatting
│   │   └── commands/              # Individual subcommand implementations
│   ├── core/
│   │   ├── architecture.py        # Subsystem boundaries & cycle detector
│   │   ├── discovery.py           # Fast path slicing & directory traversal
│   │   ├── gitignore.py           # Memoized gitignore pattern matching
│   │   ├── index_model.py         # WorkspaceIndex & batch data structures
│   │   ├── inverted_index.py      # O(1) inverted search index
│   │   ├── retrieval.py           # Evidence-grounded WorkspaceRetriever
│   │   └── search_engine.py       # Relevance-scored search engine
│   ├── knowledge/
│   │   ├── graph.py               # Directional WorkspaceGraph with O(1) edge map
│   │   ├── embeddings.py          # Local SentenceTransformers embeddings
│   │   └── vector_store.py        # In-memory vector index
│   ├── llm/
│   │   ├── base.py                # AIProvider abstractions (NVIDIA, OpenAI, Local)
│   │   ├── reasoning.py           # ReasoningEngine & prompt synthesis
│   │   └── relevance.py           # Grounding & ResponseRelevanceGrader
│   ├── services/                  # IndexingService, ExplanationService, StatusService
│   ├── storage/                   # Relational SQLiteStore & serializers
│   └── utils/                     # HTML report generator & structured logging
├── tests/
│   ├── unit/                      # 60+ modular unit test suites
│   ├── integration/               # End-to-end indexing and pipeline tests
│   └── cli/                       # CLI subcommand execution tests
├── pyproject.toml                 # PEP 517/621 build definition
└── README.md                      # Comprehensive documentation

🔒 Security & Privacy Guarantees

• Zero Hardcoded Credentials: The distribution package contains no bundled credentials or private API tokens.
• 100% Secret Masking: Keys in configuration files and console logs are automatically masked (nvapi-...***).
• Offline Determinism: Indexing, searching, impact analysis, AST parsing, and graph construction run 100% locally on your machine without external network requests.

🧪 Testing

Run the full automated test suite (185 unit, integration, and CLI tests):

# Run pytest test suite
pytest -v

# Run with test coverage report
pytest --cov=wia

📄 License

Distributed under the Apache License 2.0. See LICENSE for details.