Nuanced Python

Nuanced is an open-source library that generates enriched call graphs with static analysis annotations, providing AI coding tools with deeper understanding of code behavior.

​

Quick Start

​

Installation

uv tool install nuanced

System Requirements:

• Python >=3.10

​

Usage Modes

Nuanced offers two flexible interfaces to suit different workflows:

1. Command Line Interface
2. Python Library Interface

​

Command Line Interface

# Initialize analysis
cd my_repo
nuanced init .

# Get enriched context for a specific function
nuanced enrich relative/path/to/file.py package.module.function

​

Python Library Interface

import os
from nuanced import CodeGraph

# Initialize a graph
directory_path = os.getcwd()
graph = CodeGraph.init(directory_path)

# Get enriched context for a specific function
enrichment = graph.enrich('app/models.py', 'authenticate')

​

Core API Reference

CodeGraph provides two methods to analyze and navigate code relationships: init and enrich.

​

init

Initializes a new graph for a directory containing Python code.

init(path: str, timeout_seconds: int=60) -> CodeGraphResult

Parameters:

• path: Path to directory (e.g., ., ./src/my_package, absolute path)
• timeout_seconds: Timeout threshold in seconds. Defaults to 60.

Returns:

• CodeGraphResult containing:
  • code_graph: Successful CodeGraph instance
  • errors: List of initialization errors (if any)

Path Handling:

• Transforms relative paths to absolute paths
• Analyzes packages and non-package modules in specified directory
• Creates .nuanced directory for analysis results

Possible Errors:

• FileNotFoundError: Directory not found
• ValueError: No Python files in directory
• TimeoutError: Initialization exceeds default timeout of 60 seconds

The init command analyzes the Python files in the specified directory, creates a .nuanced directory to store analysis results where the full call graph is written to a file called nuanced-graph.json, and returns a CodeGraphResult with either the graph or any errors encountered.

​

enrich

Gets a subgraph of the full call graph focused on a specific function.

enrich(
    file_path: str,
    function_name: str,
    *,
    infer_arg_types: bool=False,
    include_builtins: bool=False
) -> Dict[str, Any]

The enrich command takes a file path and function name, and returns an EnrichmentResult containing the function’s call graph when found, and any errors encountered (e.g., ValueError when multiple matching functions exist). Unlike the result of init, which is written to a file, the result of enrich is held in memory.

When infer_arg_types is True, function argument type inference is performed and inferred types are included in the args property of function nodes.

When include_builtins is True, edges to Python’s builtins functions are included.

Parameters:

• file_path: Path to the file containing the function
• function_name: Fully qualified function name (e.g., package.submodule.function)

Returns:

• Dictionary representing a subgraph where:
  • Keys are fully qualified function names
  • Values are dictionaries containing:
    • filepath: Path to the source file
    • callees: List of fully qualified function names called by this function
• The subgraph includes the target function and all functions in its call graph (recursive traversal of outgoing edges)

Possible Errors:

• ValueError: Multiple function definitions found

Usage:

# Get enriched information for a specific function
$ nuanced enrich app/models.py authenticate

# Example output
{
  "app.models.User.authenticate": {
    "filepath": "/project/app/models.py",
    "callees": [
      "app.utils.hash_password",
      "<builtin>.dict",
      "app.database.query"
    ]
  }
}

Notes:

• The returned subgraph follows the complete call chain, not just direct function calls
• Functions not connected to the call graph of the target function are excluded
• Built-in Python functions in callees are prefixed with <builtin>.
• The subgraph preserves the structure and connections of the original graph
• Nuanced takes the file path and the function name (not the fully qualified name), the tool then resolves the fully qualified name (app.helpers.format_data) based on the file’s location and module structure.

CLI Usage:

nuanced enrich /path/to/file.py package.submodule.function

​

Graph Schema

​

Node Types

Each node in the graph represents a module, class or function. Nodes are uniquely identified by fully qualified names.

​

Node Attributes

Function nodes in the graph returned by the nuanced enrich command or CodeGraph#enrich method have the following attributes:

JSON Schema-based schemas and example JSON can be found here.

​

Inferred Types

Type inference is a Paid Tier feature.

Type inference for function return types and, optionally, function positional-or-keyword, positional-only and keyword-only argument types is performed during function enrichment for all functions in the enriched function’s call graph. The inferred_return_types and inferred_types graph attributes include annotated as well as inferred types.

The scope of analysis is currently limited as follows:

• Inference for a given function is limited to the file in which the function is defined
• No inference for starred args, e.g. *args and **kwargs
• No inference based on default argument values

​

Pricing Tiers

Nuanced is available in multiple tiers to suit different needs:

​

Free Tier

The free tier provides essential call graph functionality:

• Basic call graph generation with init and enrich commands
• Function filepath information
• List of function callees

​

Paid Tier

The paid tier enhances code analysis with additional metadata:

• All free tier features
• Inferred function return types
• Inferred function argument types
• Function signatures
• Additional context for improved AI understanding

To access paid features, contact ayman@nuanced.dev for custom licensing options.

​

Enterprise Offering

Our upcoming enterprise offering will include advanced features designed for large teams and complex codebases:

• docstring: Function documentation if available
• lines_of_code: Total lines of code in the function
• number_of_parameters: Number of parameters the function accepts
• cyclomatic_complexity: Measure of function complexity
• logical_lines_of_code: Number of executable statements

For updates on our enterprise features or to join our early access program, please email ayman@nuanced.dev.

​

Architecture

Nuanced builds upon JARVIS’ core call graph generation, extending it with a specialized focus on AI tooling integration. Call graphs are generated by jarviscg, our fork of the JARVIS Python call graph generator. We chose Jarvis (JARVIS: Scalable and Precise Application-Centered Call Graph Construction for Python) because of its:

• Precise function resolution that handles Python’s dynamic features
• Accurate handling of Python’s import system
• Application-centered approach that prioritizes relevant code paths

We’ve developed a layer on top that standardizes function identification and provides a consistent API for AI consumption. Our wrapper adds structured error handling and simplified querying capabilities that make it practical for real-world AI tooling scenarios.

​

Future Roadmap

In addition to our upcoming features, we’re researching more advanced static analysis capabilities that will further enhance code understanding:

Our long-term research focuses on:

• Function purity analysis: Identifying which functions modify state versus pure functions that don’t cause side effects.
• Control flow complexity: Providing detailed cyclomatic complexity metrics to highlight areas that need refactoring.
• Type information: Extracting and inferring parameter and return types, even in dynamically-typed code.
• Dead code detection: Finding unused functions to help maintain cleaner codebases.
• Mutation analysis: Tracking how functions modify their inputs for better reasoning about data flow.
• Scope analysis: Mapping variable access and modifications to improve understanding of code behavior.

These advanced capabilities require deeper analysis techniques and will be introduced incrementally as we refine our approach to each problem space.

For information about our versioning policy and release process, please see the Versioning and Release Guide.

​

Graph Updates

Nuanced call graphs can be updated whenever they’re most useful to you. Results are stored in local .nuanced directories that you can safely check into version control. This makes it easy to share insights with your team and track how Python code in your codebase evolves over time. This approach allows developers to:

• Regenerate call graphs as code evolves
• Integrate graph analysis into continuous integration pipelines
• Perform on-demand code introspection during development
• Share analysis results within team environments

Example

from nuanced import CodeGraph

# Update graph during development
graph = CodeGraph.init('.')

# Analyze specific functions after modifications
enrichment = graph.enrich('app/models.py', 'authenticate')

# Integrate into your development workflow
def pre_commit_analysis():
    # Generate fresh call graph before committing
    graph = CodeGraph.init('.')
    # Perform additional checks or logging
    return graph

​

Running Nuanced

Nuanced is a lightweight tool that runs anywhere Python 3.10+ is installed, supporting:

• Local development environments
• Continuous Integration (CI) systems
• Cloud platforms
• Virtual machines
• Sandboxed environments

Since Nuanced runs entirely in your environment and never sends data externally, you maintain complete control over your code analysis. Whether you’re working with proprietary code or sensitive projects, you can generate call graphs without any data leaving your systems. The library’s minimal requirements ensure consistent call graph generation across all these environments with simple setup and installation.