LSP Code Intelligence Module

Agent-centric LSP-powered code intelligence tools for symbol analysis, definition lookup, and reference finding

Overview

The LSP Code Intelligence module provides agent-centric tools that leverage Language Server Protocol (LSP) for semantic code analysis. When LSP is unavailable, it gracefully falls back to regex-based extraction.

This enables agents to:

• List symbols (functions, classes, methods) in files
• Find definitions of symbols
• Find references to symbols
• Get diagnostics (errors, warnings)

Installation

pip install praisonai

# Optional: Install Python language server for full LSP support
pip install python-lsp-server

Quick Start

import asyncio
from praisonai.cli.features import (
    create_agent_centric_tools,
    InteractiveRuntime,
    RuntimeConfig
)
from praisonaiagents import Agent

async def main():
    # Create runtime with LSP enabled
    config = RuntimeConfig(
        workspace="./my_project",
        lsp_enabled=True,
        acp_enabled=True
    )
    runtime = InteractiveRuntime(config)
    await runtime.start()
    
    # Create agent with LSP-powered tools
    tools = create_agent_centric_tools(runtime)
    
    agent = Agent(
        name="CodeAnalyzer",
        instructions="""You analyze code using LSP tools.
        Use lsp_list_symbols to list functions and classes.
        Use lsp_find_definition to find where symbols are defined.
        Use lsp_find_references to find where symbols are used.""",
        tools=tools,
        
    )
    
    # Agent uses LSP tools to analyze code
    result = agent.start("List all classes and functions in main.py")
    print(result)
    
    await runtime.stop()

asyncio.run(main())

LSP Tools

lsp_list_symbols

Lists all symbols (functions, classes, methods) in a file:

def lsp_list_symbols(file_path: str) -> str:
    """
    List all symbols in a file using LSP.
    Falls back to regex-based extraction if LSP unavailable.
    
    Args:
        file_path: Path to the file to analyze
        
    Returns:
        JSON string with list of symbols and locations
    """

Example Response:

{
  "intent": "list_symbols",
  "success": true,
  "lsp_used": true,
  "fallback_used": false,
  "data": [
    {"name": "Agent", "kind": "class", "line": 49},
    {"name": "__init__", "kind": "function", "line": 100},
    {"name": "chat", "kind": "function", "line": 500}
  ],
  "citations": [{"file": "agent.py", "type": "symbols", "count": 3}]
}

lsp_find_definition

Finds where a symbol is defined:

def lsp_find_definition(symbol: str, file_path: str = None) -> str:
    """
    Find where a symbol is defined using LSP.
    
    Args:
        symbol: The symbol name to find
        file_path: Optional file path for context
        
    Returns:
        JSON string with definition location(s)
    """

Example Response:

{
  "intent": "go_to_definition",
  "success": true,
  "lsp_used": true,
  "data": {
    "symbol": "Agent",
    "definitions": [
      {"file": "/path/to/agent.py", "line": 49, "content": "class Agent:"}
    ]
  },
  "citations": [{"file": "agent.py", "line": 49, "type": "definition"}]
}

lsp_find_references

Finds all references to a symbol:

def lsp_find_references(symbol: str, file_path: str = None) -> str:
    """
    Find all references to a symbol using LSP.
    
    Args:
        symbol: The symbol name to find references for
        file_path: Optional file path for context
        
    Returns:
        JSON string with reference locations
    """

lsp_get_diagnostics

Gets diagnostics (errors, warnings) for a file:

def lsp_get_diagnostics(file_path: str = None) -> str:
    """
    Get diagnostics for a file using LSP.
    
    Args:
        file_path: Path to the file (optional)
        
    Returns:
        JSON string with diagnostic information
    """

Fallback Behavior

When LSP is unavailable (e.g., language server not installed), the tools automatically fall back to regex-based extraction:

Tool	LSP Method	Fallback Method
lsp_list_symbols	textDocument/documentSymbol	Regex pattern matching
lsp_find_definition	textDocument/definition	Grep search for definitions
lsp_find_references	textDocument/references	Grep search for symbol usage
lsp_get_diagnostics	textDocument/publishDiagnostics	N/A (LSP only)

The response includes lsp_used and fallback_used flags to indicate which method was used.

Supported Languages

With full LSP support:

• Python - via python-lsp-server (pylsp)
• JavaScript/TypeScript - via typescript-language-server
• Go - via gopls
• Rust - via rust-analyzer

With regex fallback:

• Python (.py)
• JavaScript/TypeScript (.js, .ts, .jsx, .tsx)
• Go (.go)
• Rust (.rs)
• Java (.java)
• C/C++ (.c, .cpp, .h)

Architecture

Agent Request: "List all functions in main.py"
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│  Agent calls lsp_list_symbols("main.py")                    │
└─────────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│  CodeIntelligenceRouter                                     │
│  ├── Classify intent: LIST_SYMBOLS                         │
│  ├── Try LSP: textDocument/documentSymbol                  │
│  └── Fallback: Regex extraction if LSP fails               │
└─────────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│  Result with citations                                      │
│  {"symbols": [...], "citations": [...]}                    │
└─────────────────────────────────────────────────────────────┘

CLI Usage

# List symbols via debug CLI
praisonai debug lsp symbols main.py --json

# Find definition
praisonai debug lsp definition main.py:10:5

# Find references
praisonai debug lsp references main.py:10:5 --json

# Check LSP status
praisonai debug lsp status

Operational Notes

Performance

• LSP client is lazy-loaded only when lsp_enabled=True
• First LSP request may take longer (server startup)
• Subsequent requests are fast (server stays running)

Dependencies

• python-lsp-server (optional) - For Python LSP support
• pyright (optional) - Alternative Python LSP

Production Caveats

• LSP requires language server to be installed
• Large files may take longer to analyze
• Fallback regex is less accurate than LSP

Related

• Agent-Centric Tools - All agent-centric tools
• Debug CLI - Debug commands for LSP
• Interactive Runtime - Runtime configuration