agentic-pydoc 0.1.0__py3-none-any.whl

agentic_pydoc/__init__.py

@@ -0,0 +1,6 @@
+from .navigation import KnowledgeNavigator, NavigatorTools
+from .storage import KnowledgeStore
+
+__version__ = "0.1.0"
+
+__all__ = ["KnowledgeNavigator", "NavigatorTools", "KnowledgeStore", "__version__"]

agentic_pydoc/analyzers/behavior.py

@@ -0,0 +1,64 @@
+import ast
+from typing import override
+
+from agentic_pydoc.models import BehaviorInfo
+
+
+class BehaviorExtractor(ast.NodeVisitor):
+    def __init__(self) -> None:
+        self.scope: list[str] = []
+        self.functions: dict[str, BehaviorInfo] = {}
+
+    @override
+    def visit_ClassDef(self, node: ast.ClassDef) -> None:
+        self.scope.append(node.name)
+        self.generic_visit(node)
+        _ = self.scope.pop()
+
+    @override
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        self._function(node)
+
+    @override
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+        self._function(node)
+
+    def _function(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
+        name = ".".join(self.scope + [node.name])
+        info = BehaviorInfo(
+            name=name,
+            line=node.lineno,
+            is_async=isinstance(node, ast.AsyncFunctionDef),
+            returns=[],
+            raises=[],
+            awaits=0,
+            yields=0,
+            attributes=[],
+            context_managers=[],
+            side_effects=[],
+        )
+        self.functions[name] = info
+
+        self.scope.append(node.name)
+        for child in ast.walk(node):
+            if isinstance(child, ast.Return) and child.value:
+                info.returns.append(ast.unparse(child.value))
+            elif isinstance(child, ast.Raise) and child.exc:
+                info.raises.append(ast.unparse(child.exc))
+            elif isinstance(child, ast.Await):
+                info.awaits += 1
+            elif isinstance(child, (ast.Yield, ast.YieldFrom)):
+                info.yields += 1
+            elif isinstance(child, ast.Attribute):
+                info.attributes.append(ast.unparse(child))
+            elif isinstance(child, (ast.With, ast.AsyncWith)):
+                info.context_managers.extend(
+                    ast.unparse(item.context_expr) for item in child.items
+                )
+        _ = self.scope.pop()
+
+
+def extract_behavior(tree: ast.AST) -> dict[str, BehaviorInfo]:
+    extractor = BehaviorExtractor()
+    extractor.visit(tree)
+    return extractor.functions

agentic_pydoc/analyzers/calls.py

@@ -0,0 +1,66 @@
+import ast
+from pathlib import Path
+from typing import override
+
+from agentic_pydoc.models import CallInfo, ResolutionStatus, SourceLocation
+
+
+class CallExtractor(ast.NodeVisitor):
+    def __init__(self, path: Path | None = None) -> None:
+        self.path: Path | None = path
+        self.scope: list[str] = []
+        self.calls: list[CallInfo] = []
+
+    @override
+    def visit_ClassDef(self, node: ast.ClassDef) -> None:
+        self.scope.append(node.name)
+        self.generic_visit(node)
+        _ = self.scope.pop()
+
+    @override
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        self._function(node)
+
+    @override
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+        self._function(node)
+
+    def _function(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
+        self.scope.append(node.name)
+        self.generic_visit(node)
+        _ = self.scope.pop()
+
+    @override
+    def visit_Call(self, node: ast.Call) -> None:
+        if self.scope:
+            caller_name = ".".join(self.scope)
+            callee_expr = ast.unparse(node.func)
+            loc = (
+                SourceLocation(
+                    file=str(self.path),
+                    line=node.lineno,
+                    col_offset=node.col_offset,
+                )
+                if self.path
+                else SourceLocation(file="", line=node.lineno, col_offset=node.col_offset)
+            )
+            self.calls.append(
+                CallInfo(
+                    id=f"call:{caller_name}->{callee_expr}@{node.lineno}",
+                    caller=caller_name,
+                    callee=callee_expr,
+                    expression=callee_expr,
+                    line=node.lineno,
+                    column=node.col_offset,
+                    location=loc,
+                    confidence=1.0,
+                    status=ResolutionStatus.UNRESOLVED,
+                )
+            )
+        self.generic_visit(node)
+
+
+def extract_calls(tree: ast.AST, path: Path | None = None) -> list[CallInfo]:
+    extractor = CallExtractor(path)
+    extractor.visit(tree)
+    return extractor.calls

agentic_pydoc/analyzers/imports.py

@@ -0,0 +1,48 @@
+import ast
+from pathlib import Path
+
+from agentic_pydoc.models import ImportInfo, ImportType, SourceLocation
+
+
+def extract_imports(path: Path) -> list[ImportInfo]:
+    tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+    result: list[ImportInfo] = []
+
+    for node in ast.walk(tree):
+        loc = SourceLocation(
+            file=str(path),
+            line=getattr(node, "lineno", 1),
+            end_line=getattr(node, "end_lineno", getattr(node, "lineno", 1)),
+        )
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                imp_id = f"import:{alias.name}" if alias.name else "import"
+                result.append(
+                    ImportInfo(
+                        id=imp_id,
+                        type=ImportType.IMPORT,
+                        module=alias.name,
+                        alias=alias.asname,
+                        line=node.lineno,
+                        location=loc,
+                    )
+                )
+        elif isinstance(node, ast.ImportFrom):
+            module = node.module or ""
+            for alias in node.names:
+                name = alias.name
+                imp_id = f"import:{module}.{name}" if module else f"import:{name}"
+                result.append(
+                    ImportInfo(
+                        id=imp_id,
+                        type=ImportType.FROM,
+                        module=module,
+                        name=name,
+                        alias=alias.asname,
+                        level=node.level,
+                        line=node.lineno,
+                        location=loc,
+                    )
+                )
+
+    return result

agentic_pydoc/analyzers/inheritance.py

@@ -0,0 +1,69 @@
+from collections import defaultdict
+
+from ..models import (
+    DataKind,
+    InheritanceInfo,
+    Relationship,
+    RelationshipKind,
+    SourceLocation,
+    Symbol,
+)
+
+
+def build_inheritance(symbols: list[Symbol]) -> dict[str, list[str]]:
+    classes = {s.name for s in symbols if str(s.kind) == "class"}
+    children: dict[str, list[str]] = defaultdict(list)
+
+    for symbol in symbols:
+        if str(symbol.kind) != "class":
+            continue
+        for base in symbol.bases:
+            base_name = base.split(".")[-1]
+            if base_name in classes:
+                children[base_name].append(symbol.id)
+
+    return {k: sorted(v) for k, v in children.items()}
+
+
+def build_inheritance_models(
+    symbols: list[Symbol],
+) -> tuple[list[InheritanceInfo], list[Relationship]]:
+    class_map = {s.qualified_name: s for s in symbols if str(s.kind) == "class"}
+    name_map = {s.name: s for s in symbols if str(s.kind) == "class"}
+
+    inheritances: list[InheritanceInfo] = []
+    relationships: list[Relationship] = []
+
+    for symbol in symbols:
+        if str(symbol.kind) != "class":
+            continue
+        for base in symbol.bases:
+            parent_symbol = class_map.get(base) or name_map.get(base.split(".")[-1])
+            parent_id = parent_symbol.id if parent_symbol else base
+            resolved = parent_symbol is not None
+            loc = (
+                SourceLocation(file=symbol.file, line=symbol.line, end_line=symbol.end_line)
+                if symbol.file
+                else None
+            )
+
+            inheritances.append(
+                InheritanceInfo(
+                    child=symbol.id,
+                    parent=parent_id,
+                    resolved=resolved,
+                    location=loc,
+                )
+            )
+            relationships.append(
+                Relationship(
+                    source=symbol.id,
+                    target=parent_id,
+                    kind=RelationshipKind.INHERITS,
+                    location=loc,
+                    confidence=1.0 if resolved else 0.5,
+                    data_kind=DataKind.FACT if resolved else DataKind.INFERENCE,
+                )
+            )
+
+    return inheritances, relationships

agentic_pydoc/analyzers/symbols.py

@@ -0,0 +1,181 @@
+import ast
+from pathlib import Path
+from typing import override
+
+from ..models import (
+    Parameter,
+    ParameterKind,
+    ReturnInfo,
+    Signature,
+    SourceLocation,
+    Symbol,
+    SymbolKind,
+    make_symbol_id,
+)
+
+
+class SymbolExtractor(ast.NodeVisitor):
+    def __init__(self, path: Path, module: str) -> None:
+        self.path: Path = path
+        self.module: str = module
+        self.scope: list[str] = []
+        self.symbols: list[Symbol] = []
+
+    @override
+    def visit_ClassDef(self, node: ast.ClassDef) -> None:
+        qualified = self._qualified(node.name)
+        symbol_id = make_symbol_id(SymbolKind.CLASS, qualified)
+        loc = SourceLocation(
+            file=str(self.path),
+            line=node.lineno,
+            end_line=node.end_lineno or node.lineno,
+            col_offset=node.col_offset,
+            end_col_offset=getattr(node, "end_col_offset", None),
+        )
+        self.symbols.append(
+            Symbol(
+                id=symbol_id,
+                name=node.name,
+                qualified_name=qualified,
+                kind=SymbolKind.CLASS,
+                module=self.module,
+                file=str(self.path),
+                line=node.lineno,
+                end_line=node.end_lineno or node.lineno,
+                location=loc,
+                docstring=ast.get_docstring(node),
+                decorators=[ast.unparse(x) for x in node.decorator_list],
+                bases=[ast.unparse(x) for x in node.bases],
+                is_public=not node.name.startswith("_"),
+            )
+        )
+        self.scope.append(node.name)
+        self.generic_visit(node)
+        _ = self.scope.pop()
+
+    @override
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        self._function(node)
+
+    @override
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+        self._function(node)
+
+    def _function(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
+        qualified = self._qualified(node.name)
+        kind = SymbolKind.METHOD if self.scope else SymbolKind.FUNCTION
+        symbol_id = make_symbol_id(kind, qualified)
+        parameters = self._parameters(node)
+        returns_str = ast.unparse(node.returns) if node.returns else None
+        loc = SourceLocation(
+            file=str(self.path),
+            line=node.lineno,
+            end_line=node.end_lineno or node.lineno,
+            col_offset=node.col_offset,
+            end_col_offset=getattr(node, "end_col_offset", None),
+        )
+        signature_info = Signature(
+            parameters=parameters,
+            return_type=ReturnInfo(annotation=returns_str) if returns_str else None,
+        )
+        self.symbols.append(
+            Symbol(
+                id=symbol_id,
+                name=node.name,
+                qualified_name=qualified,
+                kind=kind,
+                module=self.module,
+                file=str(self.path),
+                line=node.lineno,
+                end_line=node.end_lineno or node.lineno,
+                location=loc,
+                signature=ast.unparse(node.args),
+                signature_info=signature_info,
+                docstring=ast.get_docstring(node),
+                decorators=[ast.unparse(x) for x in node.decorator_list],
+                parameters=parameters,
+                returns=returns_str,
+                is_async=isinstance(node, ast.AsyncFunctionDef),
+                is_public=not node.name.startswith("_"),
+            )
+        )
+        self.scope.append(node.name)
+        self.generic_visit(node)
+        _ = self.scope.pop()
+
+    def _qualified(self, name: str) -> str:
+        return ".".join([self.module, *self.scope, name])
+
+    def _parameters(
+        self, node: ast.FunctionDef | ast.AsyncFunctionDef
+    ) -> list[Parameter]:
+        args = node.args
+        posonly = args.posonlyargs
+        normal_args = args.args
+
+        # Match defaults from right to left across normal_args
+        all_pos = [*posonly, *normal_args]
+        defaults = [None] * (len(all_pos) - len(args.defaults)) + list(args.defaults)
+
+        result: list[Parameter] = []
+
+        for arg, default in zip(all_pos, defaults, strict=True):
+            pkind = (
+                ParameterKind.POSITIONAL_ONLY
+                if arg in posonly
+                else ParameterKind.POSITIONAL_OR_KEYWORD
+            )
+            default_str = ast.unparse(default) if default else None
+            result.append(
+                Parameter(
+                    name=arg.arg,
+                    kind=pkind,
+                    annotation=ast.unparse(arg.annotation) if arg.annotation else None,
+                    default=default_str,
+                    required=default_str is None,
+                )
+            )
+
+        if args.vararg:
+            result.append(
+                Parameter(
+                    name=args.vararg.arg,
+                    kind=ParameterKind.VAR_POSITIONAL,
+                    annotation=ast.unparse(args.vararg.annotation)
+                    if args.vararg.annotation
+                    else None,
+                    required=False,
+                )
+            )
+
+        for arg, default in zip(args.kwonlyargs, args.kw_defaults, strict=True):
+            default_str = ast.unparse(default) if default else None
+            result.append(
+                Parameter(
+                    name=arg.arg,
+                    kind=ParameterKind.KEYWORD_ONLY,
+                    annotation=ast.unparse(arg.annotation) if arg.annotation else None,
+                    default=default_str,
+                    required=default_str is None,
+                )
+            )
+
+        if args.kwarg:
+            result.append(
+                Parameter(
+                    name=args.kwarg.arg,
+                    kind=ParameterKind.VAR_KEYWORD,
+                    annotation=ast.unparse(args.kwarg.annotation)
+                    if args.kwarg.annotation
+                    else None,
+                    required=False,
+                )
+            )
+
+        return result
+
+
+def extract_symbols(tree: ast.AST, path: Path, module: str) -> list[Symbol]:
+    extractor = SymbolExtractor(path, module)
+    extractor.visit(tree)
+    return extractor.symbols

agentic_pydoc/analyzers/tests.py

@@ -0,0 +1,43 @@
+import ast
+from pathlib import Path
+
+from ..models import SourceLocation, TestInfo, make_test_id
+
+
+def extract_tests(path: Path, module: str) -> list[TestInfo]:
+    tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+    result: list[TestInfo] = []
+
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if not node.name.startswith("test_"):
+            continue
+
+        calls = [
+            ast.unparse(child.func)
+            for child in ast.walk(node)
+            if isinstance(child, ast.Call)
+        ]
+
+        loc = SourceLocation(
+            file=str(path),
+            line=node.lineno,
+            end_line=node.end_lineno or node.lineno,
+        )
+
+        test_id = make_test_id(module, node.name)
+        result.append(
+            TestInfo(
+                id=test_id,
+                name=node.name,
+                file=str(path),
+                line=node.lineno,
+                location=loc,
+                is_async=isinstance(node, ast.AsyncFunctionDef),
+                calls=calls,
+                confidence=1.0,
+            )
+        )
+
+    return result