WIA — Workspace Intelligence Agent

Workspace Intelligence Agent (WIA) is an enterprise-grade, graph-grounded workspace intelligence platform and codebase reasoning engine that builds a structured understanding of an entire software repository. It parses source structures, analyzes abstract syntax trees (AST), constructs rich entity relationship graphs, processes Jupyter notebooks, and grounds AI reasoning in verified codebase evidence.

Repository
    ↓
Files & Notebooks
    ↓
Source Structure & AST
    ↓
Symbols & Base Classes
    ↓
Dependencies & Call Graphs
    ↓
Architecture & Boundaries
    ↓
WorkspaceRetriever & Context Budgeting
    ↓
AI Reasoning Engine (NVIDIA NIM / Provider Abstraction)
    ↓
Evidence-Grounded Answer with Line Citations

⚡ Core Principles & Capabilities

1. Evidence-Grounded Reasoning (Zero-Hallucination Principle): Every explanation and reasoning response is derived strictly from verified workspace source files, AST symbols, imports, call graphs, tests, and configurations. Missing evidence is explicitly stated rather than replaced with generic template statements.
2. Provider-Independent AI Architecture: Modular AI provider abstraction (AIProvider) supporting NVIDIA NIM (NvidiaNimProvider), OpenAI (OpenAIProvider), Google Gemini, Anthropic Claude, and deterministic offline local reasoning (LocalReasoningProvider).
3. Strict Credential Security: The PyPI package contains no bundled credentials. Users supply their own API keys via environment variables (e.g. NVIDIA_API_KEY) or wia config / wia auth. Secrets are 100% masked in logs and CLI outputs.
4. Jupyter Notebook Understanding (.ipynb): Full cell-level parsing (markdown sections, code cells, imports, functions/classes, execution flow, output summaries) rather than classifying notebooks as "Unknown".
5. Parallel & Incremental Indexing Engine: High-speed multi-worker indexing (ThreadPoolExecutor) with SHA-256 hash delta matching, failure isolation on malformed files, and measurable performance duration metrics.
6. Multi-Tier Impact Analysis: Inspects direct dependents, indirect (transitive) dependents, symbol callers, importers, affected tests, affected examples/notebooks, and dependency paths.
7. Granular File & Tech Stack Classification: 14 functional file categories (Source Code, Notebook, Test, CI/CD, Build, Dependency Lock, Documentation, Configuration, Data, Asset, Script, Binary, Generated, Unsupported).
8. Multi-Stage Indexing Pipeline: Crawls workspace, respects .gitignore, computes SHA-256 content hashes, detects programming languages & tech stacks, and runs specialized analyzers.
9. AST & Symbol Parser: Extracts classes, functions, methods, parameters, docstrings, parent classes, and import statements across multi-language codebases.
10. Workspace Knowledge Graph: Maps directional dependency edges (IMPORTS, DEFINES, CALLS, DEPENDS_ON) between files and symbols in a persistent SQLite relational store.

1. 🏗 System Architecture & End-to-End Pipeline

              GitHub Repository URL or Local Workspace Directory
                                     │
                                     ▼
   ┌──────────────────────────────────────────────────────────────────┐
   │ 1. Repository Ingestion, Safety & Incremental Change Detector    │
   │    • Recursively scans filesystem or clones Git repository        │
   │    • Filters noise (.git, node_modules, .venv, build, binaries)  │
   │    • SHA256 file hashing for incremental change detection        │
   │    • Automatically ignores .env/keys and redacts credentials     │
   └─────────────────────────────────┬────────────────────────────────┘
                                     │
                                     ▼
   ┌──────────────────────────────────────────────────────────────────┐
   │ 2. Extensible Multi-Language Parser Plugin System                │
   │    • Python AST (classes, async functions, docstrings, calls)    │
   │    • TypeScript / JavaScript (classes, interfaces, arrow fns)    │
   │    • Go (structs, interfaces, method receivers, package imports) │
   │    • Rust (structs, enums, traits, pub fn extractors)            │
   │    • C / C++ / Java / C# (classes, interfaces, method signatures)│
   │    • Automated API route & unit test case discovery              │
   └─────────────────────────────────┬────────────────────────────────┘
                                     │
                                     ▼
   ┌──────────────────────────────────────────────────────────────────┐
   │ 3. Workspace Knowledge Model & Code Knowledge Graph              │
   │    • Entities: Repository, Subsystem, File, Symbol, Function     │
   │    • Relational Edges: CONTAINS, DEFINES, IMPORTS, CALLS, INHERIT│
   │    • Strict Provenance: DETERMINISTIC_FACT vs LLM_SUMMARY        │
   └─────────────────────────────────┬────────────────────────────────┘
                                     │
                 ┌───────────────────┼───────────────────┐
                 ▼                   ▼                   ▼
   ┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐
   │ 4A. Hierarchical  │ │ 4B. Hybrid Vector │ │ 4C. Portable OKF  │
   │     Summaries     │ │     & Lexical RAG │ │     Knowledge     │
   │     (5 Levels)    │ │     Embeddings    │ │     Export        │
   └─────────────┬─────┘ └───────────┬───────┘ └───────────┬───────┘
                 │                   │                     │
                 └───────────────────┼─────────────────────┘
                                     │
                                     ▼
   ┌──────────────────────────────────────────────────────────────────┐
   │ 5. Hybrid Retrieval Engine & Query Planner                       │
   │    • Combines Symbol Lookup + Lexical BM25 + Vector + Graph Walks │
   │    • Intent Planner: Architecture, Flow, Impact, Onboard, Health │
   │    • Structured Context Builder with Line-Number Citations       │
   └─────────────────────────────────┬────────────────────────────────┘
                                     │
                                     ▼
   ┌──────────────────────────────────────────────────────────────────┐
   │ 6. NVIDIA NIM Reasoning Layer & Grounded Output                  │
   │    • Grounded generation powered by NVIDIA NIM                   │
   │    • Exact source file and line-number citations                 │
   │    • Deterministic offline mode when NIM is not configured       │
   └─────────────────────────────────┬────────────────────────────────┘
                                     │
                                     ▼
      ┌────────────────────────────────────────────────────────┐
      │  CLI (`wia`)   │   VS Code Extension   │   REST API    │
      └────────────────────────────────────────────────────────┘

2. ⚡ Complete Technology Stack

3. 📁 Repository Directory Structure

Workspace-Intelligence-Agent/
├── backend/
│   ├── app/
│   │   ├── __init__.py                # Package version definition (v0.3.0)
│   │   ├── cli.py                     # WIA CLI command implementations
│   │   ├── main.py                    # FastAPI application & lifespan management
│   │   ├── agent/                     # WIA Code Understanding Agent
│   │   ├── api/                       # REST API routers & Pydantic models
│   │   ├── core/                      # Config, database engine, & LLM client
│   │   ├── models/                    # SQLModel workspace & knowledge entities
│   │   ├── providers/                 # NVIDIA NIM & base LLM providers
│   │   └── services/
│   │       ├── export/                # OKF exporter
│   │       ├── graph/                 # Code knowledge graph & graph traversal
│   │       ├── ingestion/             # Crawler & file discovery
│   │       ├── intelligence/          # Git diff, watcher, secret safety
│   │       ├── parser/                # Multi-language parser plugins
│   │       ├── rag/                   # VectorStore & embeddings
│   │       ├── retrieval/             # HybridRetriever, QueryPlanner, ContextBuilder
│   │       └── summarizer/            # 5-level hierarchical summarizer
│   └── tests/                         # Pytest automated test suite (26 tests)
├── docs/                              # Detailed design & user documentation
│   ├── AI_ARCHITECTURE.md             # NVIDIA NIM & Agent architecture
│   ├── API.md                         # Complete REST API reference
│   ├── ARCHITECTURE.md                # System design & component breakdown
│   ├── CLI.md                         # CLI reference manual
│   ├── HIERARCHICAL_SUMMARIZATION.md  # 5-level summarization engine
│   ├── KNOWLEDGE_MODEL.md             # Graph entities & relation schema
│   ├── OKF_EXPORT.md                  # Open Knowledge Format guide
│   ├── PACKAGING.md                   # PyPI packaging & distribution guide
│   ├── PROVENANCE.md                  # Deterministic fact vs summary model
│   ├── RETRIEVAL.md                   # Hybrid retrieval pipeline
│   └── VSCODE_EXTENSION.md            # VS Code extension architecture
├── vscode-extension/                  # Native VS Code Extension (TypeScript)
│   ├── package.json
│   ├── src/
│   │   ├── extension.ts               # Extension activation & commands
│   │   ├── api.ts                     # WIA Backend API client
│   │   ├── chatViewProvider.ts        # Interactive AI chat webview
│   │   └── treeViews.ts               # Architecture, Symbols, & Dependency trees
├── docker-compose.yml                 # Docker Compose with PostgreSQL support
├── Dockerfile.backend                 # Backend container definition
├── pyproject.toml                     # PEP 517/621 packaging metadata
├── .env.example                       # Documented environment variables template
└── README.md

4. 💻 Exhaustive Command-Line Interface (CLI) Manual

# Display CLI help and command index
wia --help

Complete CLI Command Reference

5. 🧩 Native VS Code Extension Guide

The WIA VS Code Extension embeds graph-grounded code intelligence directly into your editor:

Key Features

1. 🏛️ Architecture TreeView: Browse subsystems, root folders, and architectural components.
2. 🔍 AST Symbol Explorer: Navigate all functions, classes, interfaces, and methods in the workspace.
3. 📦 Dependencies & Imports: Inspect package manifests and import statements.
4. 🧠 Interactive AI Chat: Natural-language codebase Q&A with clickable source citations that jump directly to exact file line ranges in the VS Code editor.
5. ⚡ Editor Context Menu Actions:
   • WIA: Explain Code Architecture
   • WIA: Trace Code Execution Flow
   • WIA: Analyze Change Impact
   • WIA: Export Open Knowledge Format (.wia/knowledge/)

6. 🚀 Quickstart & Installation Guide

PyPI Installation

# Install WIA distribution from PyPI
pip install wia-agent

# Verify CLI installation
wia --help

# Alternatively, run directly via Python module (works without PATH configuration):
python -m wia --help

Local Development Setup

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

# 2. Install package in editable development mode with dev tools
pip install -e ".[dev]"

# 3. Configure environment variables
cp .env.example .env

Running via WIA Engine Daemon

# Start the local daemon for CLI and VS Code extension
wia serve

Docker Compose Deployment

# Run backend engine with PostgreSQL
docker-compose up --build

7. 📡 Complete REST API Reference

Base URL: http://127.0.0.1:8000/api/v1

8. 🧠 Workspace Knowledge Model & Code Knowledge Graph

WIA structures repository understanding into first-class typed entities:

• Repository: Top-level workspace metadata, entry points, dependencies.
• FileNode: File/directory structure with language classification and SHA256 hashes.
• ASTSymbol: Extracted classes, functions, methods, variables, interfaces, and imports with line numbers.
• WorkspaceSummary: 5-level structured responsibilities with confidence scores.

The Code Knowledge Graph represents relationships:

• CONTAINS (Directory → File, File → Class)
• DEFINES (File → Function / Class)
• IMPORTS (File → Module)
• CALLS (Function → Function / Method)
• INHERITS (Class → Base Class)

9. 🔌 Multi-Language AST Parser Plugin Architecture

WIA features dedicated parser plugins:

• Python: Full ast parsing for classes, async functions, decorators, method binding, docstrings, and call invocations.
• TypeScript & JavaScript: Extracts exported interfaces, types, ES6 classes, arrow functions, and imported modules.
• Go: Extracts package declarations, structs, interfaces, and method receivers.
• Rust: Extracts structs, enums, traits, implementations, and pub fn functions.
• C / C++ / Java / C#: Extracts class definitions, interfaces, methods, and header includes.

10. 📊 5-Level Hierarchical Workspace Summarization Engine

1. Level 1 (Function/Method): Deterministic purpose and signature.
2. Level 2 (File/Module): Primary responsibility and defined symbols.
3. Level 3 (Child Folder): Component domain grouping.
4. Level 4 (Parent Folder / Subsystem): Subsystem boundaries and architectural responsibility.
5. Level 5 (Repository Architecture): Executive repository purpose, tech stack, entry points.

11. 🔍 Hybrid Retrieval Engine & Query Planner

WIA combines multiple retrieval strategies:

• Exact Symbol Lookup: Instant index lookup for symbols matching query terms.
• Lexical BM25 Search: Matches identifiers, docstrings, and signatures.
• Semantic Vector Search: SentenceTransformers embeddings for conceptual queries.
• Graph Traversal: Inbound/outbound graph walks for callers, callees, and dependencies.

The Query Planner classifies query intent:

• CODE_FLOW: Traces call paths.
• DEPENDENCY_IMPACT: Calculates blast radius.
• ONBOARDING: Synthesizes walkthrough.
• HEALTH_AUDIT: Computes complexity metrics.
• GENERAL_QA: Synthesizes grounded answer.

12. 🤖 NVIDIA NIM AI Reasoning Provider

WIA uses NVIDIA NIM (NeMo Inference Microservices) as its primary LLM reasoning layer:

DEFAULT_LLM_PROVIDER=nvidia
NVIDIA_NIM_API_KEY=nvapi-your-key-here
NVIDIA_NIM_BASE_URL=https://integrate.api.nvidia.com/v1
NVIDIA_NIM_MODEL=meta/llama-3.1-70b-instruct

• Grounded Reasoning: The LLM receives only retrieved repository facts, symbols, and graph context.
• Offline Deterministic Fallback: If NVIDIA NIM is not configured, deterministic analysis commands (scan, architecture, symbols, flow, impact, export) continue working seamlessly.

13. 🛡️ Provenance & Secret Safety Redaction

• Strict Provenance: WIA distinguishes DETERMINISTIC_FACT (parsed symbols, imports, lines) from LLM_SUMMARY (AI-generated text).
• Secret Safety: Sensitive files (.env, .pem, .key, id_rsa) and patterns (API keys, tokens) are redacted before constructing LLM context.

14. 📦 Open Knowledge Format (OKF) Export

Export codebase intelligence into portable Markdown:

wia export "My Project" --format okf --output ./

Generates .wia/knowledge/:

.wia/knowledge/
├── index.md           # Knowledge index & tech stack
├── repository.md      # Executive summary & entry points
├── architecture.md    # Subsystems breakdown
├── subsystems/        # Subsystem deep dives
├── modules/           # Per-file module guides
└── symbols/           # Defined symbols index

15. ⚙️ Complete Configuration & Environment Variables (.env)

# ==============================================================================
# Workspace Intelligence Agent (WIA) - Environment Configuration
# ==============================================================================

DEFAULT_LLM_PROVIDER=nvidia
NVIDIA_NIM_API_KEY=your_nvidia_nim_api_key_here
NVIDIA_NIM_BASE_URL=https://integrate.api.nvidia.com/v1
NVIDIA_NIM_MODEL=meta/llama-3.1-70b-instruct

# Local Vector Embeddings (SentenceTransformers)
EMBEDDING_MODEL=all-MiniLM-L6-v2

# Server Configuration
WIA_HOST=127.0.0.1
WIA_PORT=8000
WIA_LOG_LEVEL=INFO

16. 🧪 Automated Testing Suite

Run the full automated pytest suite (26 unit & integration tests, 55% measured test coverage):

# Run pytest with coverage
pytest --cov=app

# Or via WIA CLI
wia test

Verified Test Suites

• test_api_endpoints.py: Tests all REST API endpoints with SQLite memory pool.
• test_ast_multilang.py: Validates Python, TypeScript, Go, Rust, and C++ AST symbol extraction.
• test_knowledge_graph.py: Validates BFS call tracing, impact analysis, and graph edges.
• test_hybrid_retrieval.py: Validates Query Planner intents, secret redaction, and OKF export.
• test_nvidia_nim_provider.py: Validates NVIDIA NIM provider request building, authentication, and fallback.
• test_wia_pipeline.py: Validates crawler, AST parser, hierarchical summarizer, and agent.

17. ❓ Troubleshooting & FAQ

Q: Do I need an OpenAI / Gemini API key to use WIA?
A: No. WIA uses NVIDIA NIM as its primary AI provider. If no LLM keys are provided, deterministic commands (scan, architecture, symbols, flow, impact, export) continue working completely.

Q: How does the VS Code extension connect to WIA?
A: Start the daemon with wia serve (or python run_dev.py). The VS Code extension connects to http://127.0.0.1:8000.

1. Installation

Install wia-agent from PyPI:

pip install wia-agent

Verify the installation:

wia --version
wia doctor

Deterministic features (index, summary, search, explain, impact, architecture, flow, diff) run completely offline without an API key. To enable LLM reasoning for wia ask:

# Option A: Set via Environment Variable
export NVIDIA_API_KEY="nvapi-..."

# 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

🛠️ CLI Command Reference

1. wia index — Parallel & Incremental Workspace Indexing

Crawls the workspace, respects .gitignore, detects languages & file types, computes SHA-256 hashes, parses AST symbols, builds the WorkspaceGraph, and scans for security leaks.

# Standard indexing
wia index

# Index with 8 parallel worker threads
wia index --workers 8

# Force complete re-indexing
wia index --force-reindex

2. wia summary — Structured Repository Intelligence

Generates a comprehensive summary separating factual statistics from architectural intelligence.

wia summary

• Repository Facts: Discovered vs indexed files, languages breakdown, file types (Source, Notebooks, Tests, CI/CD, Manifests), total classes and functions.
• Repository Intelligence: Project purpose, categorized technology stack, entry points, and subsystem architecture.

3. wia search — Relevance-Aware Workspace Search

Queries file paths, exact symbols, functions, classes, and docstrings, providing exact line numbers and relevance explanations.

wia search Application
wia search "state persistence"
wia search --type class --language Python

4. wia explain — Code & Notebook Explanation

Produces 13-section technical breakdowns for source files, Jupyter notebooks, or individual symbols.

# Explain a source file
wia explain wia/core/retrieval.py

# Explain a Jupyter notebook
wia explain notebooks/analysis.ipynb

# Explain a specific function or class
wia explain WorkspaceRetriever

5. wia impact — Multi-Tier Refactoring Impact Analysis

Analyzes blast radius, direct callers, indirect transitive dependents, affected unit tests, and affected example workflows.

wia impact wia/core/index_model.py
wia impact WorkspaceIndex

6. wia ask — Evidence-Grounded AI Reasoning

Asks natural-language questions about codebase architecture, execution flow, component relationships, or debugging.

wia ask "Explain the project"
wia ask "How does application execution work?"
wia ask "What depends on WorkspaceRetriever?"
wia ask "Where are unit tests located and how is indexing tested?"

🏗️ Architecture

               WIA CLI (Click)
                      │
           Intent Classification & Routing
                      │
       ┌──────────────┴──────────────┐
       │                             │
Deterministic Engine           Reasoning Engine
       │                             │
 ┌─────┴──────────────┐       ┌──────┴──────────────┐
 │ IndexingService    │       │ WorkspaceRetriever  │
 │ ASTParser          │       │ Context Budgeting   │
 │ NotebookParser     │       │ Evidence Assembly   │
 │ WorkspaceGraph     │       │ AIProvider Layer    │
 │ ImpactAnalyzer     │       │  ├─ NvidiaNim       │
 │ SearchEngine       │       │  ├─ OpenAI          │
 └────────────────────┘       │  └─ LocalReasoning  │
                              └─────────────────────┘

🔒 Security & Privacy

• Zero Hardcoded Secrets: No credentials or private tokens are packaged or committed.
• 100% Secret Masking: Any API keys in environment or configuration files are masked (nvapi-...***).
• Offline Determinism: Indexing, searching, impact analysis, and graph building run 100% locally on your machine.

🧪 Testing

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

python -m pytest -v

📄 License

Apache License 2.0. Distributed as wia-agent on PyPI.