docs(api): sync Python API reference to python-sdk 1.4.0 (#6)

Co-authored-by: rahlk <1433964+rahlk@users.noreply.github.com>

Author: rahlk

src/content/docs/reference/python-api/core.md

@@ -140,9 +140,9 @@ The full generated reference follows.
 
 <!-- AUTO-GENERATED by scripts/gen_api_docs.py, do not edit by hand. -->
 
-[![Source on GitHub](https://img.shields.io/badge/source-codellm--devkit%2Fpython--sdk-181717?logo=github&logoColor=white)](https://github.com/codellm-devkit/python-sdk) [![cldk 1.2.0](https://img.shields.io/badge/cldk-1.2.0-3776AB?logo=pypi&logoColor=white)](https://pypi.org/project/cldk/1.2.0/)
+[![Source on GitHub](https://img.shields.io/badge/source-codellm--devkit%2Fpython--sdk-181717?logo=github&logoColor=white)](https://github.com/codellm-devkit/python-sdk) [![cldk 1.4.0](https://img.shields.io/badge/cldk-1.4.0-3776AB?logo=pypi&logoColor=white)](https://pypi.org/project/cldk/1.4.0/)
 
-_API reference generated from cldk 1.2.0._
+_API reference generated from cldk 1.4.0._
 
 Core CLDK module.
 
@@ -155,8 +155,8 @@ parsers, and sanitization utilities.
 > **The CLDK supports the following languages**
 > - **Java**: Full static analysis via CodeAnalyzer backend, including symbol
 >   tables, call graphs, and code metrics.
-> - **Python**: Static analysis via codeanalyzer-python backend with optional
->   CodeQL-augmented call graph resolution.
+> - **Python**: Static analysis via codeanalyzer-python backend (Jedi plus
+>   PyCG call-graph construction).
 > - **C**: Basic analysis via libclang for parsing and extracting code structure.
 
 Typical usage involves instantiating `CLDK` with a target language, then
@@ -221,7 +221,7 @@ Create a Java analysis facade.
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| `project_path` | `str \| Path \| None` | Path to the Java project directory. |
+| `project_path` | `str \| Path \| None` | Path to the Java project directory. Optional only when ``backend`` is a `Neo4jConnectionConfig` (the graph is read out of band over Bolt). When provided, the path is validated, it must exist and be a directory, regardless of backend. |
 | `source_code` | `str \| None` | Single Java source string (deprecated; pass ``project_path`` instead). |
 | `analysis_level` | `str` | Analysis depth (see `AnalysisLevel`). |
 | `target_files` | `List[str] \| None` | Restrict analysis to these files. |
@@ -244,7 +244,7 @@ Create a Python analysis facade.
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| `project_path` | `str \| Path \| None` | Path to the Python project directory. Optional only when ``backend`` is a `Neo4jConnectionConfig` (the graph is populated out of band). |
+| `project_path` | `str \| Path \| None` | Path to the Python project directory. Optional only when ``backend`` is a `Neo4jConnectionConfig` (the graph is populated out of band over Bolt). When provided, the path is validated, it must exist and be a directory, regardless of backend. |
 | `analysis_level` | `str` | Analysis depth (see `AnalysisLevel`). |
 | `target_files` | `List[str] \| None` | Restrict analysis to these files. |
 | `eager` | `bool` | Force regeneration of cached analysis. |
@@ -262,11 +262,11 @@ Create a TypeScript analysis facade.
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| `project_path` | `str \| Path \| None` | Path to the TypeScript project directory. Optional only when ``backend`` is a `Neo4jConnectionConfig` (the graph is populated out of band). |
+| `project_path` | `str \| Path \| None` | Path to the TypeScript project directory. Optional only when ``backend`` is a `Neo4jConnectionConfig` (the graph is populated out of band over Bolt). When provided, the path is validated, it must exist and be a directory, regardless of backend. |
 | `analysis_level` | `str` | Analysis depth (see `AnalysisLevel`). |
 | `target_files` | `List[str] \| None` | Restrict analysis to these files. |
 | `eager` | `bool` | Force regeneration of cached analysis. |
-| `backend` | `TSBackend \| None` | Backend configuration. Defaults to `CodeAnalyzerConfig`; pass a `Neo4jConnectionConfig` to use the read-only Neo4j backend. |
+| `backend` | `TSBackend \| None` | Backend configuration. Defaults to `CodeAnalyzerConfig`; pass a `TSCodeAnalyzerConfig` to set TypeScript-only knobs such as ``tsc_only`` (passes ``--tsc-only``), or a `Neo4jConnectionConfig` to use the read-only Neo4j backend. |
 
 #### `CLDK.c`
 
@@ -279,7 +279,7 @@ Create a C analysis facade for the given project directory.
 #### `CLDK.analysis`
 
 ```python
-analysis(project_path: str | Path | None = None, source_code: str | None = None, eager: bool = False, analysis_level: str = AnalysisLevel.symbol_table, target_files: List[str] | None = None, analysis_backend_path: str | None = None, analysis_json_path: str | Path | None = None, cache_dir: str | Path | None = None, use_codeql: bool = True, use_ray: bool = False, neo4j_config: Neo4jConnectionConfig | None = None) -> JavaAnalysis | PythonAnalysis | CAnalysis | TypeScriptAnalysis
+analysis(project_path: str | Path | None = None, source_code: str | None = None, eager: bool = False, analysis_level: str = AnalysisLevel.symbol_table, target_files: List[str] | None = None, analysis_backend_path: str | None = None, analysis_json_path: str | Path | None = None, cache_dir: str | Path | None = None, use_ray: bool = False, neo4j_config: Neo4jConnectionConfig | None = None) -> JavaAnalysis | PythonAnalysis | CAnalysis | TypeScriptAnalysis
 ```
 
 Deprecated entry point. Use the per-language factory methods instead.

src/content/docs/reference/python-api/java.md

@@ -106,9 +106,9 @@ follows.
 
 <!-- AUTO-GENERATED by scripts/gen_api_docs.py, do not edit by hand. -->
 
-[![Source on GitHub](https://img.shields.io/badge/source-codellm--devkit%2Fpython--sdk-181717?logo=github&logoColor=white)](https://github.com/codellm-devkit/python-sdk) [![cldk 1.2.0](https://img.shields.io/badge/cldk-1.2.0-3776AB?logo=pypi&logoColor=white)](https://pypi.org/project/cldk/1.2.0/)
+[![Source on GitHub](https://img.shields.io/badge/source-codellm--devkit%2Fpython--sdk-181717?logo=github&logoColor=white)](https://github.com/codellm-devkit/python-sdk) [![cldk 1.4.0](https://img.shields.io/badge/cldk-1.4.0-3776AB?logo=pypi&logoColor=white)](https://pypi.org/project/cldk/1.4.0/)
 
-_API reference generated from cldk 1.2.0._
+_API reference generated from cldk 1.4.0._
 
 ## Analysis
 

src/content/docs/reference/python-api/python.md

@@ -123,9 +123,9 @@ follows.
 
 <!-- AUTO-GENERATED by scripts/gen_api_docs.py, do not edit by hand. -->
 
-[![Source on GitHub](https://img.shields.io/badge/source-codellm--devkit%2Fpython--sdk-181717?logo=github&logoColor=white)](https://github.com/codellm-devkit/python-sdk) [![cldk 1.2.0](https://img.shields.io/badge/cldk-1.2.0-3776AB?logo=pypi&logoColor=white)](https://pypi.org/project/cldk/1.2.0/)
+[![Source on GitHub](https://img.shields.io/badge/source-codellm--devkit%2Fpython--sdk-181717?logo=github&logoColor=white)](https://github.com/codellm-devkit/python-sdk) [![cldk 1.4.0](https://img.shields.io/badge/cldk-1.4.0-3776AB?logo=pypi&logoColor=white)](https://pypi.org/project/cldk/1.4.0/)
 
-_API reference generated from cldk 1.2.0._
+_API reference generated from cldk 1.4.0._
 
 ## Analysis
 
@@ -140,8 +140,7 @@ The analysis is powered by the ``codeanalyzer-python`` backend, which uses a
 combination of:
     - **Jedi**: For semantic code understanding, symbol resolution, and basic
       call graph construction.
-    - **CodeQL** (optional): For enhanced call graph resolution and more
-      accurate inter-procedural analysis.
+    - **PyCG**: For call-graph construction.
     - **Tree-sitter**: For fast syntactic parsing and AST operations.
 
 > **Key capabilities include**
@@ -416,16 +415,15 @@ from one callable to another.
 
 > **The call graph is built using**
 > - Jedi for semantic call resolution
-> - CodeQL (if enabled) for enhanced inter-procedural analysis
+> - PyCG for inter-procedural call-graph construction
 
 **Returns:**
 
 - `nx.DiGraph`: A ``networkx.DiGraph`` where: - Nodes represent callables (functions/methods) with attributes containing callable metadata - Edges represent call relationships, directed from caller to callee - Edge attributes may include call site information
 
 > **Note**
-> The completeness of the call graph depends on the analysis
-> configuration. With ``use_codeql=True``, more call relationships
-> are typically discovered at the cost of longer analysis time.
+> The completeness of the call graph depends on the analysis backend
+> (Jedi plus PyCG in codeanalyzer-python 0.3.0).
 
 > **See Also**
 > `get_callers`: For finding callers of a specific method.
@@ -559,6 +557,94 @@ dictionary structure by class name and then method name.
 > `get_methods_in_class`: For methods of a specific class.
 > `get_method`: For a single method by name.
 
+##### `PythonAnalysis.get_callables_overview`
+
+```python
+get_callables_overview() -> List[PyCallableOverview]
+```
+
+Return a lightweight overview of every callable in the project, in one bulk read.
+
+A field-projected alternative to `get_methods` for enumeration: each
+`PyCallableOverview` carries the callable's signature, owning
+class (if any), kind, location, and decorators, but not the full reconstruction (call
+sites, inner callables, locals). On the Neo4j backend this is a single Cypher query instead
+of the per-entity fan-out `get_methods` pays. Body-inspect the few you need afterwards
+via `get_method` or `get_method_bodies`.
+
+**Returns:**
+
+- `List[PyCallableOverview]`: A flat list of `PyCallableOverview`, one per callable
+- `List[PyCallableOverview]`: (methods, module-level functions, and nested functions).
+
+> **See Also**
+> `get_decorated_callables`: The same projection filtered by decorator.
+> `get_method_bodies`: Bulk source-body fetch for chosen signatures.
+
+##### `PythonAnalysis.get_method_bodies`
+
+```python
+get_method_bodies(signatures: List[str]) -> Dict[str, str]
+```
+
+Return source bodies for the given callable signatures, in one bulk read.
+
+**Parameters:**
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| `signatures` | `List[str]` | Callable signatures to fetch bodies for (e.g. from `get_callables_overview`). |
+
+**Returns:**
+
+- `Dict[str, str]`: A dict mapping each signature to its source body. Signatures with no matching callable
+- `Dict[str, str]`: are omitted.
+
+##### `PythonAnalysis.get_decorated_callables`
+
+```python
+get_decorated_callables(markers: List[str]) -> List[PyCallableOverview]
+```
+
+Return overviews of callables decorated with any of the given markers, in one bulk read.
+
+**Parameters:**
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| `markers` | `List[str]` | Decorator names to match (e.g. ``["staticmethod", "app.route"]``). |
+
+**Returns:**
+
+- `List[PyCallableOverview]`: A list of `PyCallableOverview` for every callable carrying at
+- `List[PyCallableOverview]`: least one of ``markers`` as a decorator.
+
+> **See Also**
+> `get_callables_overview`: The unfiltered projection.
+
+##### `PythonAnalysis.get_callsites_for`
+
+```python
+get_callsites_for(signatures: List[str]) -> Dict[str, List[PyCallsite]]
+```
+
+Return the call sites of the given callables, keyed by signature, in one bulk read.
+
+Avoids the per-callable reconstruction fan-out when you need call sites for a specific
+frontier (e.g. dispatch-edge synthesis or external-reader detection).
+
+**Parameters:**
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| `signatures` | `List[str]` | Callable signatures to fetch call sites for. |
+
+**Returns:**
+
+- `Dict[str, List[PyCallsite]]`: A dict mapping each existing signature to its list of
+- `Dict[str, List[PyCallsite]]`: class:`~cldk.models.python.PyCallsite` (empty if the callable has no call sites).
+- `Dict[str, List[PyCallsite]]`: Signatures with no matching callable are omitted.
+
 ##### `PythonAnalysis.get_methods_in_class`
 
 ```python
@@ -1233,6 +1319,7 @@ Represents a Python application.
 | ---- | ---- | ----------- |
 | `symbol_table` | `Dict[str, PyModule]` |  |
 | `call_graph` | `List[PyCallEdge]` |  |
+| `external_symbols` | `Dict[str, PyExternalSymbol]` |  |
 
 ### `PyCallEdge`
 
@@ -1256,7 +1343,7 @@ Rich per-call metadata (receiver, arguments, location, ...) lives on
 | `target` | `str` |  |
 | `type` | `Literal['CALL_DEP']` |  |
 | `weight` | `int` |  |
-| `provenance` | `List[Literal['jedi', 'codeql', 'joern']]` |  |
+| `provenance` | `List[Literal['jedi', 'pycg', 'joern']]` |  |
 
 ### `PyCallable`
 
@@ -1288,6 +1375,32 @@ Represents a Python callable (function/method).
 | `local_variables` | `List[PyVariableDeclaration]` |  |
 | `cyclomatic_complexity` | `int` |  |
 
+### `PyCallableOverview`
+
+```python
+class PyCallableOverview(BaseModel)
+```
+
+A lightweight projection of one callable, enough to enumerate and filter without the full
+`PyCallable` reconstruction (call-sites, inner callables, locals).
+
+Returned set-at-a-time by `get_callables_overview` /
+`get_decorated_callables`. Body-inspect only the few you need afterwards
+via `get_method`/`get_method_bodies`.
+
+#### Attributes
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| `signature` | `str` |  |
+| `name` | `str` |  |
+| `class_signature` | `Optional[str]` |  |
+| `kind` | `str` |  |
+| `path` | `str` |  |
+| `start_line` | `int` |  |
+| `end_line` | `int` |  |
+| `decorators` | `List[str]` |  |
+
 ### `PyCallableParameter`
 
 ```python

src/content/docs/reference/python-api/typescript.md

@@ -53,9 +53,9 @@ graph = analysis.get_call_graph()  # -> networkx.DiGraph
 
 <!-- AUTO-GENERATED by scripts/gen_api_docs.py, do not edit by hand. -->
 
-[![Source on GitHub](https://img.shields.io/badge/source-codellm--devkit%2Fpython--sdk-181717?logo=github&logoColor=white)](https://github.com/codellm-devkit/python-sdk) [![cldk 1.2.0](https://img.shields.io/badge/cldk-1.2.0-3776AB?logo=pypi&logoColor=white)](https://pypi.org/project/cldk/1.2.0/)
+[![Source on GitHub](https://img.shields.io/badge/source-codellm--devkit%2Fpython--sdk-181717?logo=github&logoColor=white)](https://github.com/codellm-devkit/python-sdk) [![cldk 1.4.0](https://img.shields.io/badge/cldk-1.4.0-3776AB?logo=pypi&logoColor=white)](https://pypi.org/project/cldk/1.4.0/)
 
-_API reference generated from cldk 1.2.0._
+_API reference generated from cldk 1.4.0._
 
 ## Analysis
 
@@ -134,6 +134,16 @@ The phantom (external) call targets, imported/required library members the call
 points at (e.g. ``node:fs.readFileSync``, ``js-yaml.load``). Useful for source→sink
 reachability.
 
+##### `TypeScriptAnalysis.get_synthesized_callables`
+
+```python
+get_synthesized_callables() -> Dict[str, TSSynthesizedCallable]
+```
+
+The synthesized anonymous-callback endpoints the call graph points at, Jelly-resolved
+callbacks the symbol table never names (keyed by their ``<host>:<line:col>`` signature).
+Empty under the ``tsc``-only resolver. Materialized so anonymous call edges don't dangle.
+
 ##### `TypeScriptAnalysis.get_call_graph_json`
 
 ```python
@@ -436,6 +446,7 @@ The root analysis object emitted as analysis.json.
 | `symbol_table` | `Dict[str, TSModule]` |  |
 | `call_graph` | `List[TSCallEdge]` |  |
 | `external_symbols` | `Dict[str, TSExternalSymbol]` |  |
+| `synthesized_callables` | `Dict[str, TSSynthesizedCallable]` |  |
 
 ### `TSCallEdge`
 
@@ -895,6 +906,30 @@ A symbol referenced or declared in code.
 | `lineno` | `int` |  |
 | `col_offset` | `int` |  |
 
+### `TSSynthesizedCallable`
+
+```python
+class TSSynthesizedCallable(_Base)
+```
+
+A first-party anonymous callback that Jelly resolves as a call-graph endpoint but the symbol
+table never names (the canonicalizer returns ``null`` for anonymous functions). Materialized so
+that ``call_graph`` edges to anonymous callbacks don't dangle.
+
+Slim, like `TSExternalSymbol`: the map key in ``TSApplication.synthesized_callables`` IS
+the synthesized signature ``<nearest-named-enclosing-signature>:<line:col>``, so an edge's
+``source``/``target`` byte-matches it just like a real ``TSCallable.signature``. The ``tsc``
+resolver emits an empty map; Jelly (the union default) populates it.
+
+#### Attributes
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| `name` | `str` |  |
+| `path` | `str` |  |
+| `start_line` | `int` |  |
+| `start_column` | `int` |  |
+
 ### `TSTypeAlias`
 
 ```python