WorksComputer Science
Typify: A Tool for Usage-driven Type Inference in Python
Abstract
Python's dynamic type system, while expressive and flexible, creates significant challenges for static analysis tools in unannotated or partially annotated codebases. Existing approaches either require pre-existing type annotations, or depend on deep learning models that demand large training corpora and significant computational resources. We present Typify, a lightweight, usage-driven static type inference engine that infers precise type information across entire Python projects without annotations or training data. Typify integrates symbolic execution, fixpoint analysis, and context-matching retrieval to propagate types across modules, functions, and recursive call structures. The tool is available as both a command-line interface (CLI) for batch inference, evaluation and downstream integration with other tools, and a Visual Studio Code (VS Code) extension for interactive type assistance. Evaluation on the ManyTypes4Py and Typilus datasets shows that Typify outperforms all static baselines and closely matches state-of-the-art hybrid deep learning approaches, while running approximately 10x faster.
Introduction
Modern software development increasingly relies on Python, yet Python’s dynamic type system means that most real-world code carries no type annotations. Empirical studies show that fewer than 10% of annotatable code elements are typed in practice [1]. Without type information, tools such as linters, static analyzers, and IDEs cannot provide reliable support, and bugs that could be caught early surface only at runtime. While Python’s gradual typing standards [2] allow developers to add annotations voluntarily, doing so manually in large or legacy codebases is tedious and error-prone.
Several categories of tools attempt to address this gap. Static type checkers such as Mypy [3], Pyre [4], and Pyright [5] are effective when annotations are already present, but fall back to Any when they are not. Deep learning-based tools such as Type4Py [6] and Typilus [7] achieve broad coverage but are non-deterministic, require large training corpora, and perform poorly on project-specific or user-defined types. Hybrid approaches like HiTyper [8] combine static reasoning with neural predictions, but operate at the function level and inherit the reproducibility limitations of the models they rely on.
In this paper, we present TYPIFY, a tool for usage-driven static type inference in Python. TYPIFY infers types by reasoning about how variables, functions, and data structures are used across a project, rather than relying on annotations or training data. It builds a project-level dependency graph and propagates type information across modules using fixpoint analysis. For unresolved slots, a context-matching retrieval step fills the remaining gaps without sacrificing determinism. TYPIFY is available as both a command-line interface (CLI) and a Visual Studio Code (VS Code) extension. A complete description of the underlying technique is available in our technical paper [9].
Approach
TYPIFY operates in four stages. We briefly describe each stage below. Full algorithmic details, including formal definitions and threshold selections, can be found elsewhere [9].
Dependency Graph Construction
Before inference begins, TYPIFY scans the project root and identifies all Python modules, including those nested within packages. Each module is assigned a fully qualified name and represented as a node in a dependency graph, where an edge indicates that imports . The graph is built by traversing each module’s abstract syntax tree (AST) and extracting its import statements. This gives TYPIFY a precise map of inter-module relationships that governs the order and scope of all downstream inference.
Real-world projects often contain circular imports. TYPIFY detects strongly connected components (SCCs) in the dependency graph and treats each SCC as a unified analysis region, iterating inference within it until all module snapshots stabilize.
Scheduling and Fixpoint Resolution
Once the dependency graph is built, TYPIFY schedules modules for analysis. For projects without circular imports, modules are processed in topological order, so that any types inferred in a dependency are available when its dependents are analyzed. For cyclic dependencies, TYPIFY iterates over each SCC, comparing each module’s type snapshot after every pass. Analysis terminates when no snapshot changes, guaranteeing convergence. In practice, most projects complete in a single forward pass.
Usage-Driven Inference
Usage-driven inference is the core of TYPIFY. Rather than relying on annotations or training data, TYPIFY infers types directly from how variables, functions, and data structures are used. All inferred types are represented as TypeExpr instances, a uniform recursive structure capturing a base type and any nested type arguments.
class TypeExpr:
base: TypeExpr
args: list[TypeExpr]
For each module, TYPIFY constructs a symbol table and traverses the module body statement by statement. Assignments, function calls, and return statements all contribute evidence that refines the inferred type of each type slot. Type updates are monotonic: types only become more specific or remain unchanged, so analysis always converges. Figure 1 illustrates this process.

Figure 1. Example of usage-driven and call-site-driven inference.
The call site
collect_items(True)provides concrete evidence thatflagisbool, which TYPIFY propagates to the parameter slot before entering the function body.items = []establishes a provisional type oflist[Any].items.append(1)refines the slot tolist[int].items.append("x")unifies the existing type withlist[str], producinglist[Union[int, str]].The return statement binds the inferred type of
itemsto the function’s return slot, givinglist[Union[int, str]].
Context-Matching Retrieval
After usage-driven inference, some type slots may remain unknown, for example in uncalled functions or sparsely used variables. For these cases, TYPIFY applies a context-matching retrieval step. It queries a pre-built index of (context, type) pairs extracted from an annotated codebase, matching each uninferred slot against indexed entries by the similarity of their surrounding source context. Retrieved candidates are treated as suggestions rather than definitive answers, and they never override a type already established by usage-driven inference. TYPIFY assigns three confidence levels to its predictions: high for usage-driven results, mid for retrieval matches, and low for name-convention heuristics applied when retrieval yields no result.
Architecture
Figure 2 shows an overview of TYPIFY’s architecture. The pipeline begins with the Dependency Graph Builder, which scans the project and constructs a module-level import graph, establishing the order and scope of all downstream analysis. The SCCs Finder identifies strongly connected components in this graph to handle circular imports, grouping mutually dependent modules into unified analysis regions. The Symbol Table Builder then constructs a symbol table for each module, mapping identifiers to their scopes and definitions. These are passed to the Typeslots Collector, which extracts all type slots — the specific locations in the code where a type is to be inferred. The Inference Engine performs usage-driven type inference over these slots, propagating types from call sites, assignments, and return statements. The Stability Checker determines whether the fixpoint has been reached by comparing type snapshots across passes, feeding updated typeslots back into the Inference Engine if not. Once stable, the Retrieval Querier fills any remaining uninferred slots by querying a pre-built index of annotated code for contextually similar entries. Finally, the Export Results component writes the inferred types to JSON artifacts consumed by downstream tools or the VS Code extension.

Figure 2. An overview of TYPIFY’s architecture.
Implementation
TYPIFY is available in two forms: a command-line interface (CLI) for batch inference and evaluation, and a Visual Studio Code (VS Code) extension for interactive use.
The TYPIFY inference engine implements the four-stage pipeline described in Section II. It is distributed as a standalone Python package with a command-line interface, and requires Python 3.11 or later. Installation and invocation are covered in § 5. The available commands are summarized in Table I. A config.json file can be passed to the relevant commands via the --config flag, and allows users to adjust parameters of the inference pipeline, including the number of top- results returned by context-matching retrieval, whether context-matching retrieval is enabled, whether the deep learning model integration is enabled, and other inference parameters. TYPIFY runs the inference pipeline and writes the inferred types as JSON artifacts. Each entry records the inferred type, its confidence level, and the source location of the type slot. The developer can adjust inference behaviour by editing config.json, toggling context-matching retrieval and Type4Py integration, or adjusting the usage-driven inference parameters to balance accuracy and performance.
| Command | Description |
typify infer <project-path> <output-path> [--config <config-path>] | Runs inference on a project and writes inferred types to the output file. |
typify gt <dataset-path> <output-path> | Extracts ground-truth type annotations from an annotated dataset. |
typify dataset <dataset-path> <output-path> [--config <config-path>] | Runs batch inference over a dataset and saves predictions for evaluation. |
typify eval <gt-path> <tool-path> | Evaluates predictions against ground truth using type-matching metrics. |
typify build <dataset-path> <index-path> [--workers <n>] | Builds a retrieval index from an annotated Python corpus. |
Table I. Summary of Typify CLI commands. More details of these commands can be found in [10].
Case II: Interactive Type Assistance via the VS Code Extension
Consider a developer working on a legacy Python codebase. They encounter a function with no type annotations and want to understand its expected inputs and return type. The developer hovers over the function definition, and the TYPIFY overlay appears, showing inferred types for each parameter and the return value. The panel also lists the known call sites from which these types were derived, including the observed argument types and return value, allowing the developer to verify the evidence behind each inferred type. The developer clicks Annotate, and TYPIFY inserts type annotations for the function’s parameters and return value directly into the source file. The function is now typed, allowing type mismatches to be caught statically rather than at runtime. Figure 3 illustrates this workflow across all three stages.

Figure 3. Using TYPIFY in VS Code: (a) unannotated function in the editor, (b) hover overlay showing inferred types, call sites, and the Annotate button, (c) the function after clicking Annotate with type annotations inserted.
Usage Scenarios
Case I: Batch Type Inference via the CLI
Consider a developer who wants to run type inference over a Python project to feed inferred types into a downstream tool, such as a static analyzer or documentation generator. They install the inference engine via pip install typify-cli and invoke the typify infer command (see Table I for the full list of available commands):
typify infer <project-path> <output-path>
Evaluation
This section summarizes the quantitative evaluation of TYPIFY. Full details of the evaluation procedure and results can be found in the technical paper [9].
Setup. We evaluate TYPIFY on two datasets: ManyTypes4Py [13], a benchmark of Python projects with type annotations, and the Typilus dataset [7], consisting of annotations collected from 600 Python repositories. We report two metrics: exact match, where a prediction is correct only if it matches the ground truth in both base type and type arguments, and base match, where type arguments are ignored. We compare TYPIFY against three compared techniques: Pyre Infer [4], an industry static type checker developed by Meta; HiTyper [8], a hybrid approach that combines static inference with deep learning; and Type4Py [6], a deep learning-based tool. We also evaluate TYPIFY + Type4Py, where Type4Py serves as a fallback for low-confidence slots, and compare it against HiTyper + Type4Py.
Results. TYPIFY outperforms all compared techniques by substantial margins on both datasets (Table II). On Many-Types4Py, it improves over HiTyper’s static component by 11.7–16.5 points overall, with especially large gains on argument types (35–40 points), and by 45–56 points over Pyre Infer. TYPIFY also beats Type4Py overall despite being fully static. Combined with Type4Py as a fallback, TYPIFY + Type4Py surpasses HiTyper + Type4Py on most tasks, e.g., 75.0% vs. 74.2% exact match for variable types, and a 14.7-point gain on argument prediction. The same trend holds on the Typilus dataset, confirming the hybrid combination sets a new state of the art across both benchmarks.
| Task | Approach | ManyTypes4Py EM | ManyTypes4Py BM | Typilus EM | Typilus BM |
| Variable | TYPIFY | 62.7 | 74.7 | 18.5 | 55.3 |
| Variable | TYPIFY + Type4Py | 75.0 | 86.5 | 19.0 | 65.2 |
| Variable | HiTyper | 57.0 | 63.8 | 16.3 | 52.7 |
| Variable | HiTyper + Type4Py | 74.2 | 81.6 | 18.3 | 63.3 |
| Variable | Type4Py | 55.2 | 60.1 | 14.4 | 33.6 |
| Variable | Pyre Infer | 6.9 | 7.1 | 0.9 | 1.1 |
| Argument | TYPIFY | 43.0 | 47.7 | 49.2 | 52.2 |
| Argument | TYPIFY + Type4Py | 60.0 | 65.5 | 65.4 | 69.4 |
| Argument | HiTyper | 7.8 | 8.1 | 7.0 | 7.1 |
| Argument | HiTyper + Type4Py | 45.3 | 47.7 | 52.1 | 54.0 |
| Argument | Type4Py | 46.0 | 47.9 | 50.3 | 51.7 |
| Argument | Pyre Infer | 9.4 | 9.4 | 8.8 | 8.8 |
| Return | TYPIFY | 38.4 | 50.5 | 31.6 | 44.0 |
| Return | TYPIFY + Type4Py | 48.0 | 60.4 | 40.6 | 55.2 |
| Return | HiTyper | 34.0 | 43.7 | 26.9 | 37.5 |
| Return | HiTyper + Type4Py | 46.8 | 56.9 | 40.7 | 52.9 |
| Return | Type4Py | 33.9 | 36.4 | 29.4 | 32.4 |
| Return | Pyre Infer | 35.2 | 36.2 | 27.3 | 28.3 |
Table 2. TOP-1 TYPE PREDICTION ACCURACY (%). EM = EXACT MATCH, BM = BASE MATCH.
Inference Speed. TYPIFY requires an average of 4.7 ms per data point on ManyTypes4Py, compared to 48.2 ms for HiTyper and 36.5 ms for Type4Py, corresponding to a 90% reduction in latency relative to HiTyper. A similar trend holds on the Typilus dataset, where TYPIFY requires 3.9 ms per data point compared to 45.3 ms for HiTyper. Since TYPIFY is fully static, these figures exclude training time, which Type4Py and HiTyper both require.
User Study
We conducted a user study to assess the usefulness of TYPIFY and to identify any usability issues. All five participants are Computer Science students with at least three years of Python programming experience. As this is a small-scale study, our results should be read as preliminary evidence rather than a general claim of effectiveness. To avoid the confound of participants struggling with an unfamiliar codebase, we developed a controlled Python project implementing a library management system, covering operations such as checking books in and out, managing loans, and tracking members; we view this toy project as a useful first step, and plan to evaluate TYPIFY on larger, real-world codebases with more participants in future work.
Each participant completed a set of tasks with and without the TYPIFY VS Code extension enabled. Tasks included adding new functionality, adjusting existing functions, and identifying expected types in unfamiliar parts of the code. When working without TYPIFY, participants used Pylance (which uses Pyright), the standard Python type inference environment that ships with the VS Code Python extension. Participants completed tasks without TYPIFY first, then repeated equivalent tasks with the extension enabled, followed by an interview.
All five participants agreed that TYPIFY helped them understand the codebase more quickly. Pylance and Pyright fell back to Any for unannotated functions, giving participants little actionable information. TYPIFY inferred concrete types and surfaced the call sites from which those types were derived, which participants found particularly useful for understanding not just what type was inferred, but why. The Annotate button also reduced the friction of adding annotations manually. Without TYPIFY, participants took noticeably longer to reason about types and in several cases introduced type mismatches that would only have surfaced at runtime.
The study also surfaced several areas for improvement. Two participants noted that TYPIFY could not provide linter features such as auto-completion. One participant suggested the sidebar show the Type4Py API endpoint and allow changing it for custom self-hosted instances — we found this valuable and incorporated it. The remaining features are currently under active development.
Related Work
A number of static type checkers are available for Python, including but not limited to Mypy [3], Pyre [4], Pyright [5], and Pytype [14]. However, these tools focus on type checking rather than inference, and often default to Any when annotations are missing, limiting their usefulness for legacy or unannotated codebases.
To address this, several tools infer types using neural models trained on large code corpora. Typilus [7] uses graph neural networks, Type4Py [6] applies deep similarity learning, DeepTyper [15] uses sequence models, and TypeWriter [16] uses search-based validation. More recent work has explored LLM-based annotation generation [17], [18], and HiTyper [8] combines static analysis with deep learning over type dependency graphs. These LLM-based assistants generate annotations by predicting plausible tokens from patterns learned during training, rather than by verifying how a value is actually constructed and used, so their output can vary across runs and is not guaranteed to be consistent with the surrounding project. TYPIFY instead derives each annotation deterministically by tracing concrete usage through the project’s dependency graph, so a given codebase always yields the same, traceable result. However, existing approaches are either non-deterministic, limited to function-level inference, or struggle with project-specific types. TYPIFY requires no training data, produces deterministic results, and performs whole-project inference, with TYPIFY + Type4Py outperforming HiTyper + Type4Py on most tasks. Beyond Python, gradual typing systems such as TypeScript [19] and Flow [20] combine inference with constraint solving.
Limitations
TYPIFY handles the majority of real-world Python code well, as reflected in its evaluation results across diverse open-source repositories. However, several language features present challenges for purely static analysis. Metaprogramming constructs and decorators that dynamically modify definitions at runtime are not fully supported, and dynamic imports cannot be resolved through the dependency graph. For example, consider the following code:
module_name = "os.path"
mod = importlib.import_module(module_name)
result = mod.join("usr", "bin")
Since the module name is determined at runtime, TYPIFY cannot resolve the type of mod or result statically, and falls back to Any for those slots. Higher-order functions are supported in common cases, but complex patterns involving mutual recursion or context-dependent signatures may not be fully resolved, causing TYPIFY to fall back to Any for the affected slots. Support for several of these features is currently under active development. In practice, these limitations rarely affect usability since the majority of Python codebases do not rely heavily on such constructs.
Conclusion
We present TYPIFY, a tool for usage-driven static type inference in Python. TYPIFY infers types by reasoning about and tracing how variables, functions, and data structures are used throughout an entire project, without relying on existing type annotations or training data. It is available both as a Visual Studio Code extension for interactive use and as a command-line interface for batch inference and integration with downstream tools. TYPIFY not only outperforms traditional static analysis and deep learning–based approaches in type inference accuracy, but also performs inference significantly faster (e.g., TYPIFY is approximately 10× faster than HiTyper), making it practical for real-time use in developer tools. The source code and datasets are publicly available, enabling other researchers to replicate and extend our work [10]. The demonstration will showcase how TYPIFY can be used in a variety of usage scenarios.
References
- [1]L. D. Grazia and M. Pradel, “The evolution of type annotations in Python: An empirical study,” in Proceedings of the 30th ACM Joint European Software Engineering Conference and Symposium on the Foundations of Software Engineering (ESEC/FSE), 2022, pp. 209–220.
- [2]G. van Rossum, J. Lehtosalo, and Lukasz Langa, “PEP 484: Type hints,” https://peps.python.org/pep-0484/, 2014, retrieved Jan 29, 2026.
- [3]Mypy Contributors, “Mypy,” https://mypy-lang.org/, 2026, retrieved Jan 29, 2026.
- [4]Meta Platforms, “Pyre,” https://pyre-check.org/, 2026, retrieved Jan 29, 2026.
- [5]Microsoft, “Pyright,” https://microsoft.github.io/pyright/, 2026, retrieved Jan 29, 2026.
- [6]A. M. Mir, E. Latoškinas, S. Proksch, and G. Gousios, “Type4Py: Practical deep similarity learning-based type inference for Python,” in Proceedings of the 44th International Conference on Software Engineering (ICSE), 2022, pp. 2241–2252.DOI
- [7]M. Allamanis, E. T. Barr, S. Ducousso, and Z. Gao, “Typilus: Neural type hints,” in Proceedings of the 41st ACM SIGPLAN Conference on Programming Language Design and Implementation (PLDI), 2020, pp. 91–105.DOI
- [8]Y. Peng, C. Gao, Z. Li, B. Gao, D. Lo, Q. Zhang, and M. Lyu, “Static inference meets deep learning: A hybrid type inference approach for Python,” in Proceedings of the 44th International Conference on Software Engineering (ICSE), 2022, pp. 2019–2030.DOI
- [9]A. Aman, M. Asaduzzaman, and S. Wang, “Typify: A lightweight usage-driven static analyzer for precise Python type inference,” in Proceedings of the 34th IEEE/ACM International Conference on Program Comprehension (ICPC ’26), 2026, to appear.
- [10]A. Aman, “Typify CLI repository,” https://github.com/ali-aman-burki/typify-cli, 2026, retrieved Jan 29, 2026.
- [13]A. M. Mir, E. Latoškinas, and G. Gousios, “ManyTypes4Py: A benchmark Python dataset for machine learning-based type inference,” in Proceedings of the IEEE/ACM 18th International Conference on Mining Software Repositories (MSR), 2021, pp. 585–589.arxiv.org/abs/2104.04706
- [14]Google, “Pytype,” https://google.github.io/pytype/, 2026, retrieved Jan 29, 2026.
- [15]V. J. Hellendoorn, C. Bird, E. T. Barr, and M. Allamanis, “Deep learning type inference,” in Proceedings of the 26th ACM Joint European Software Engineering Conference and Symposium on the Foundations of Software Engineering (ESEC/FSE), 2018, pp. 152–162.DOI
- [16]M. Pradel, G. Gousios, J. Liu, and S. Chandra, “TypeWriter: Neural type prediction with search-based validation,” in Proceedings of the 28th ACM Joint European Software Engineering Conference and Symposium on the Foundations of Software Engineering (ESEC/FSE), 2020, pp. 209–220.arxiv.org/abs/1912.03768
- [17]Y. Zhang et al., “Generating Python type annotations from type inference,” Communications of the ACM, 2024.
- [18]Y. Peng, C. Gao, Z. Li, D. Lo, and M. Lyu, “Generative type inference for Python,” arXiv, 2023.arxiv.org/abs/2307.09163
- [19]Microsoft, “TypeScript,” https://www.typescriptlang.org/, 2026, retrieved Jan 29, 2026.
- [20]Meta Platforms, “Flow,” https://flow.org/, 2026, retrieved Jan 29, 2026.