Code Intelligence API Reference

Complete reference for the types and protocols used by the language handler plugin system.

Module: faos_api.knowledge_fabric.code.parsers.protocol

EntityType

class EntityType(str, enum.Enum):
    CLASS = "class"
    FUNCTION = "function"
    METHOD = "method"
    MODULE_VARIABLE = "module_variable"
    ENUM = "enum"
    INTERFACE = "interface"
    TYPE_ALIAS = "type_alias"

Enum identifying the kind of code entity. Used as CodeEntity.entity_type.

Value	When to use
CLASS	Class/struct definitions
FUNCTION	Module-level / package-level functions
METHOD	Functions nested inside a class or struct
MODULE_VARIABLE	Top-level constants and variables
ENUM	Enum definitions (Python enum.Enum, Java enum, etc.)
INTERFACE	Interface definitions (TypeScript, Go, Java, C#)
TYPE_ALIAS	Type alias definitions

CodeEntity

class CodeEntity(BaseModel):
    name: str
    qualified_name: str = ""
    file_path: str = ""
    line_start: int = 0
    line_end: int = 0
    signature: str = ""
    docstring: str | None = None
    entity_type: EntityType = EntityType.FUNCTION

    # Extended fields
    decorators: list[str] = []
    parameters: list[str] = []
    base_classes: list[str] = []
    is_async: bool = False
    is_static: bool = False
    is_classmethod: bool = False
    is_property: bool = False
    parent_class: str | None = None
    enum_members: list[str] = []

Pydantic model representing a single extracted code entity. This is the unified output type for all language handlers (Platform 2.0).

Core Fields

Field	Type	Description
name	str	Simple name (e.g., MyClass, calculate)
qualified_name	str	Dot-separated path (e.g., pkg.module.MyClass)
file_path	str	Path to source file
line_start	int	1-based start line
line_end	int	1-based end line
signature	str	Full signature text (e.g., def foo(x: int) -> str)
docstring	str | None	Extracted documentation string
entity_type	EntityType	Kind of entity

Extended Fields

Field	Type	Description
decorators	list[str]	Decorator names (@app.get -> "app.get")
parameters	list[str]	Parameter names
base_classes	list[str]	Base class / parent type names
is_async	bool	Whether async function/method
is_static	bool	Whether static method
is_classmethod	bool	Whether classmethod (Python)
is_property	bool	Whether property (Python/C#)
parent_class	str | None	Enclosing class name (for methods)
enum_members	list[str]	Enum member names (for enums)

LanguageHandler Protocol

@runtime_checkable
class LanguageHandler(Protocol):
    def parse(self, source: str, *, file_path: str = "", module_path: str = "") -> list[CodeEntity]: ...
    def extract_classes(self, root: Node, source: bytes) -> Sequence[ClassInfo]: ...
    def extract_functions(self, root: Node, source: bytes) -> Sequence[FunctionInfo]: ...
    def extract_methods(self, cls_node: Node, source: bytes) -> Sequence[MethodInfo]: ...
    def extract_imports(self, root: Node, source: bytes) -> Sequence[ImportInfo]: ...
    def extract_exports(self, root: Node, source: bytes) -> Sequence[ExportInfo]: ...
    def extract_inheritance(self, cls_node: Node, source: bytes) -> Sequence[InheritanceInfo]: ...
    def extract_enums(self, root: Node, source: bytes) -> Sequence[EnumInfo]: ...
    def extract_interfaces(self, root: Node, source: bytes) -> Sequence[InterfaceInfo]: ...
    def get_qualified_name(self, node: Node, module_path: str) -> str: ...
    def package_indicator_files(self) -> list[str]: ...
    def resolve_module_system(self, import_str: str, file_path: str) -> str: ...
    def custom_tree_sitter_queries(self) -> dict[str, str]: ...

Runtime-checkable protocol that all handlers must satisfy. Use isinstance(handler, LanguageHandler) to verify conformance.

Required Methods

parse(source, *, file_path, module_path) -> list[CodeEntity]

Primary entry point. Parse source code and return all entities.

• Must never raise -- catch all exceptions internally, return [] on failure.
• source: Source code as a string.
• file_path: Populates CodeEntity.file_path.
• module_path: Used to build CodeEntity.qualified_name (e.g., "pkg.module").

extract_classes(root, source) -> Sequence[ClassInfo]

Extract class definitions from the AST root node. Legacy method -- still required for backward compatibility.

extract_functions(root, source) -> Sequence[FunctionInfo]

Extract module-level function definitions.

extract_methods(cls_node, source) -> Sequence[MethodInfo]

Extract methods from within a class AST node.

extract_imports(root, source) -> Sequence[ImportInfo]

Extract import/require statements.

extract_exports(root, source) -> Sequence[ExportInfo]

Extract explicit export declarations (Python __all__, TypeScript export, Go exported names).

extract_inheritance(cls_node, source) -> Sequence[InheritanceInfo]

Extract base class / parent type relationships.

extract_enums(root, source) -> Sequence[EnumInfo]

Extract enum definitions.

extract_interfaces(root, source) -> Sequence[InterfaceInfo]

Extract interface definitions. Return [] for languages without interfaces.

get_qualified_name(node, module_path) -> str

Build a fully qualified name for an AST node.

package_indicator_files() -> list[str]

Return file names that indicate a directory is a package (e.g., ["__init__.py"] for Python, ["package.json"] for Node.js).

resolve_module_system(import_str, file_path) -> str

Return the module system identifier (e.g., "python", "esm", "cjs", "go").

Optional Method

custom_tree_sitter_queries() -> dict[str, str]

Return language-specific Tree-sitter S-expression queries for advanced AST patterns. Default implementation returns {}.

Legacy Data Models

These dataclasses are used by the legacy extract_* methods. New code should prefer CodeEntity.

Model	Fields
ClassInfo	name, qualified_name, start_line, end_line, decorators, docstring, base_classes
FunctionInfo	name, qualified_name, start_line, end_line, decorators, docstring, parameters, is_async
MethodInfo	name, qualified_name, start_line, end_line, decorators, docstring, parameters, is_async, is_static, is_classmethod, is_property
ImportInfo	module_path, imported_names, alias, is_relative, is_external
ExportInfo	exported_name, is_default
InheritanceInfo	base_class_name, base_module_path
EnumInfo	name, qualified_name, start_line, end_line, members, docstring
InterfaceInfo	name, qualified_name, start_line, end_line, extends, docstring
TypeAliasInfo	name, qualified_name, start_line, end_line

Handler Registry

Module: faos_api.knowledge_fabric.code.parsers.handler_registry

LANGUAGE_HANDLERS

LANGUAGE_HANDLERS: dict[str, Callable[[], LanguageHandler]]

Maps language identifiers to factory functions. Each call produces a new handler instance.

handler = LANGUAGE_HANDLERS["python"]()
entities = handler.parse(source, file_path="foo.py")

Current entries: python, typescript, javascript, tsx, jsx, java, c_sharp, go.

get_handler(language) -> LanguageHandler | None

Convenience function that looks up the factory and creates an instance. Returns None if the language is not registered or the factory fails.

HandlerRegistry (class-based, legacy)

Instance-based registry with register(), get(), supported_languages(), is_supported() methods. Used by create_default_registry().

Tree-sitter Parser

Module: faos_api.knowledge_fabric.code.parsers.tree_sitter_parser

detect_language(file_path) -> str | None

Detect language from file extension. Returns None for unsupported files.

TreeSitterParser

Core parser class with caching. Key methods:

• parse(file_path, language=None) -> Tree -- parse a file
• parse_bytes(source_bytes, language) -> Tree -- parse raw bytes