Praison AI

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

bash
pip install praisonai

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

Quick Start

python
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:

python
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:

json
{
  "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:

python
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:

json
{
  "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:

python
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:

python
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:

ToolLSP MethodFallback Method
lsp_list_symbolstextDocument/documentSymbolRegex pattern matching
lsp_find_definitiontextDocument/definitionGrep search for definitions
lsp_find_referencestextDocument/referencesGrep search for symbol usage
lsp_get_diagnosticstextDocument/publishDiagnosticsN/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

bash
# 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