@pmaddire/gcie 0.1.2

package/knowledge_index/models.py

@@ -0,0 +1,35 @@
+"""Knowledge index data models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class FunctionIndexEntry:
+    name: str
+    file: str
+    start_line: int
+    end_line: int
+    parameters: tuple[str, ...]
+    variables_read: tuple[str, ...]
+    variables_written: tuple[str, ...]
+    functions_called: tuple[str, ...]
+    docstring: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class ClassIndexEntry:
+    name: str
+    file: str
+    methods: tuple[str, ...]
+    attributes: tuple[str, ...]
+    base_classes: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class FileIndexEntry:
+    path: str
+    imports: tuple[str, ...]
+    classes_defined: tuple[str, ...]
+    functions_defined: tuple[str, ...]

package/knowledge_index/query_api.py

@@ -0,0 +1,38 @@
+"""Knowledge index query API."""
+
+from __future__ import annotations
+
+from .models import ClassIndexEntry, FileIndexEntry, FunctionIndexEntry
+from .store import InMemoryKnowledgeStore
+
+
+def find_functions_modifying_variable(store: InMemoryKnowledgeStore, variable: str) -> tuple[FunctionIndexEntry, ...]:
+    return tuple(
+        fn
+        for fn in store.functions.values()
+        if variable in fn.variables_written
+    )
+
+
+def find_functions_calling_function(store: InMemoryKnowledgeStore, function_name: str) -> tuple[FunctionIndexEntry, ...]:
+    return tuple(
+        fn
+        for fn in store.functions.values()
+        if function_name in fn.functions_called
+    )
+
+
+def find_files_importing_module(store: InMemoryKnowledgeStore, module_name: str) -> tuple[FileIndexEntry, ...]:
+    return tuple(
+        file
+        for file in store.files.values()
+        if any(imp == module_name or imp.startswith(f"{module_name}.") for imp in file.imports)
+    )
+
+
+def find_classes_inheriting_from(store: InMemoryKnowledgeStore, base_class: str) -> tuple[ClassIndexEntry, ...]:
+    return tuple(
+        cls
+        for cls in store.classes.values()
+        if base_class in cls.base_classes
+    )

package/knowledge_index/store.py

@@ -0,0 +1,23 @@
+"""In-memory storage for knowledge index."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .models import ClassIndexEntry, FileIndexEntry, FunctionIndexEntry
+
+
+@dataclass(slots=True)
+class InMemoryKnowledgeStore:
+    functions: dict[str, FunctionIndexEntry] = field(default_factory=dict)
+    classes: dict[str, ClassIndexEntry] = field(default_factory=dict)
+    files: dict[str, FileIndexEntry] = field(default_factory=dict)
+
+    def add_function(self, entry: FunctionIndexEntry) -> None:
+        self.functions[f"{entry.file}::{entry.name}"] = entry
+
+    def add_class(self, entry: ClassIndexEntry) -> None:
+        self.classes[f"{entry.file}::{entry.name}"] = entry
+
+    def add_file(self, entry: FileIndexEntry) -> None:
+        self.files[entry.path] = entry

package/llm_context/__init__.py

@@ -0,0 +1,6 @@
+"""LLM context package."""
+
+from .context_builder import ContextPayload, build_context
+from .snippet_selector import RankedSnippet, select_snippets
+
+__all__ = ["ContextPayload", "RankedSnippet", "build_context", "select_snippets"]

package/llm_context/context_builder.py

@@ -0,0 +1,67 @@
+"""Context builder for minimal LLM prompts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .snippet_selector import RankedSnippet, estimate_tokens, select_snippets
+
+
+@dataclass(frozen=True, slots=True)
+class ContextPayload:
+    query: str
+    snippets: tuple[RankedSnippet, ...]
+    total_tokens_estimate: int
+
+
+
+
+_INTENT_BASE = {
+    "edit": 300,
+    "refactor": 600,
+    "debug": 500,
+    "explore": 400,
+}
+
+
+def _detect_intent(query: str) -> str:
+    text = query.lower()
+    if any(word in text for word in ("refactor", "rewrite", "migrate", "restructure")):
+        return "refactor"
+    if any(word in text for word in ("debug", "why", "error", "fail", "bug", "trace")):
+        return "debug"
+    if any(word in text for word in ("add", "change", "update", "extend", "modify", "remove", "rename")):
+        return "edit"
+    return "explore"
+
+
+def _auto_budget(query: str, ranked_snippets: list[RankedSnippet], intent: str) -> int:
+    """Compute a context budget that scales with intent, query, and candidate size."""
+    q_tokens = estimate_tokens(query)
+    count = len(ranked_snippets)
+
+    base = _INTENT_BASE.get(intent, 400)
+    budget = base + min(300, q_tokens * 10) + min(400, count * 30)
+    return max(200, min(1600, budget))
+
+
+def build_context(
+    query: str,
+    ranked_snippets: list[RankedSnippet],
+    *,
+    token_budget: int | None = 800,
+    mandatory_node_ids: set[str] | None = None,
+    intent: str | None = None,
+) -> ContextPayload:
+    """Build minimal context payload for LLM usage."""
+    if token_budget is None:
+        detected_intent = _detect_intent(query) if intent is None else intent
+        token_budget = _auto_budget(query, ranked_snippets, detected_intent)
+
+    selected = select_snippets(
+        ranked_snippets,
+        token_budget=token_budget,
+        mandatory_node_ids=mandatory_node_ids,
+    )
+    total = sum(estimate_tokens(item.content) for item in selected)
+    return ContextPayload(query=query, snippets=selected, total_tokens_estimate=total)

package/llm_context/snippet_selector.py

@@ -0,0 +1,57 @@
+"""Snippet selection logic for LLM context packaging."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class RankedSnippet:
+    node_id: str
+    content: str
+    score: float
+
+
+def estimate_tokens(text: str) -> int:
+    """Cheap token estimate for budget management."""
+    return max(1, len(text.split()))
+
+
+def select_snippets(
+    ranked: list[RankedSnippet],
+    *,
+    token_budget: int,
+    mandatory_node_ids: set[str] | None = None,
+) -> tuple[RankedSnippet, ...]:
+    """Select minimal high-value snippets under token budget."""
+    mandatory_node_ids = mandatory_node_ids or set()
+
+    selected: list[RankedSnippet] = []
+    seen_contents: set[str] = set()
+    used_tokens = 0
+
+    # First, include mandatory snippets if possible.
+    for item in ranked:
+        if item.node_id not in mandatory_node_ids:
+            continue
+        if item.content in seen_contents:
+            continue
+        t = estimate_tokens(item.content)
+        if used_tokens + t > token_budget:
+            continue
+        selected.append(item)
+        seen_contents.add(item.content)
+        used_tokens += t
+
+    # Then fill with highest score snippets.
+    for item in sorted(ranked, key=lambda s: s.score, reverse=True):
+        if item.content in seen_contents:
+            continue
+        t = estimate_tokens(item.content)
+        if used_tokens + t > token_budget:
+            continue
+        selected.append(item)
+        seen_contents.add(item.content)
+        used_tokens += t
+
+    return tuple(selected)

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@pmaddire/gcie",
+  "version": "0.1.2",
+  "description": "GraphCode Intelligence Engine one-command setup and context CLI",
+  "bin": {
+    "gcie": "bin/gcie.js",
+    "gcie-init": "bin/gcie-init.js"
+  },
+  "scripts": {
+    "gcie": "node bin/gcie.js",
+    "setup": "node bin/gcie-init.js"
+  },
+  "license": "MIT"
+}

package/parser/__init__.py

@@ -0,0 +1,18 @@
+"""Parser package for GCIE."""
+
+from .ast_parser import parse_python_file
+from .models import (
+    ClassEntry,
+    FunctionEntry,
+    ModuleParseResult,
+    VariableAccess,
+)
+
+__all__ = [
+    "ClassEntry",
+    "FunctionEntry",
+    "ModuleParseResult",
+    "VariableAccess",
+    "parse_python_file",
+]
+

package/parser/ast_parser.py

@@ -0,0 +1,216 @@
+"""AST parser for Python source files."""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from .models import (
+    AssignmentEntry,
+    ClassEntry,
+    FunctionEntry,
+    ImportEntry,
+    ModuleParseResult,
+    VariableAccess,
+)
+
+
+class _FunctionAnalyzer(ast.NodeVisitor):
+    """Extract variable reads/writes and called function names."""
+
+    def __init__(self) -> None:
+        self.reads: set[str] = set()
+        self.writes: set[str] = set()
+        self.calls: set[str] = set()
+        self.accesses: list[VariableAccess] = []
+
+    def visit_Name(self, node: ast.Name) -> None:
+        if isinstance(node.ctx, ast.Load):
+            self.reads.add(node.id)
+            self.accesses.append(VariableAccess(name=node.id, line=node.lineno, access_type="read"))
+        elif isinstance(node.ctx, ast.Store):
+            self.writes.add(node.id)
+            self.accesses.append(VariableAccess(name=node.id, line=node.lineno, access_type="write"))
+        self.generic_visit(node)
+
+    def visit_Attribute(self, node: ast.Attribute) -> None:
+        dotted = _attribute_name(node)
+        if dotted:
+            if isinstance(node.ctx, ast.Load):
+                self.reads.add(dotted)
+                self.accesses.append(VariableAccess(name=dotted, line=node.lineno, access_type="read"))
+            elif isinstance(node.ctx, ast.Store):
+                self.writes.add(dotted)
+                self.accesses.append(VariableAccess(name=dotted, line=node.lineno, access_type="write"))
+        self.generic_visit(node)
+
+    def visit_Call(self, node: ast.Call) -> None:
+        call_name = _call_name(node.func)
+        if call_name:
+            self.calls.add(call_name)
+        self.generic_visit(node)
+
+
+class _ClassAnalyzer(ast.NodeVisitor):
+    """Extract class-level attributes and method names."""
+
+    def __init__(self) -> None:
+        self.attributes: set[str] = set()
+        self.methods: set[str] = set()
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:  # pragma: no cover - simple dispatch
+        self.methods.add(node.name)
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:  # pragma: no cover - simple dispatch
+        self.methods.add(node.name)
+
+    def visit_Assign(self, node: ast.Assign) -> None:
+        for target in node.targets:
+            for name in _extract_target_names(target):
+                self.attributes.add(name)
+        self.generic_visit(node)
+
+
+def _extract_target_names(target: ast.expr) -> list[str]:
+    names: list[str] = []
+    if isinstance(target, ast.Name):
+        names.append(target.id)
+    elif isinstance(target, ast.Attribute):
+        dotted = _attribute_name(target)
+        if dotted:
+            names.append(dotted)
+    elif isinstance(target, (ast.Tuple, ast.List)):
+        for element in target.elts:
+            names.extend(_extract_target_names(element))
+    return names
+
+
+def _attribute_name(node: ast.Attribute) -> str:
+    parts: list[str] = []
+    current: ast.AST = node
+    while isinstance(current, ast.Attribute):
+        parts.append(current.attr)
+        current = current.value
+    if isinstance(current, ast.Name):
+        parts.append(current.id)
+        return ".".join(reversed(parts))
+    return ""
+
+
+def _annotation_to_name(node: ast.expr) -> str:
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        base = _annotation_to_name(node.value)
+        return f"{base}.{node.attr}" if base else node.attr
+    if isinstance(node, ast.Subscript):
+        return _annotation_to_name(node.value)
+    return ""
+
+
+def _call_name(node: ast.expr) -> str:
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        base = _call_name(node.value)
+        return f"{base}.{node.attr}" if base else node.attr
+    return ""
+
+
+def _end_lineno(node: ast.AST) -> int:
+    return getattr(node, "end_lineno", getattr(node, "lineno", 0))
+
+
+def parse_python_source(source: str, file: str | Path = "<memory>") -> ModuleParseResult:
+    """Parse Python source into a normalized module parse result."""
+    file_path = Path(file)
+    try:
+        tree = ast.parse(source)
+    except SyntaxError as exc:
+        return ModuleParseResult(file=file_path, parse_errors=(str(exc),))
+
+    functions: list[FunctionEntry] = []
+    classes: list[ClassEntry] = []
+    imports: list[ImportEntry] = []
+    assignments: list[AssignmentEntry] = []
+
+    for node in tree.body:
+        if isinstance(node, ast.Import):
+            imports.append(
+                ImportEntry(
+                    module="",
+                    names=tuple(alias.name for alias in node.names),
+                    line=node.lineno,
+                )
+            )
+        elif isinstance(node, ast.ImportFrom):
+            imports.append(
+                ImportEntry(
+                    module=node.module or "",
+                    names=tuple(alias.name for alias in node.names),
+                    line=node.lineno,
+                )
+            )
+        elif isinstance(node, ast.Assign):
+            for target in node.targets:
+                for name in _extract_target_names(target):
+                    assignments.append(AssignmentEntry(target=name, line=node.lineno))
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            analyzer = _FunctionAnalyzer()
+            analyzer.visit(node)
+
+            parameters: list[str] = [arg.arg for arg in node.args.args]
+            parameters.extend(arg.arg for arg in node.args.kwonlyargs)
+            if node.args.vararg:
+                parameters.append(node.args.vararg.arg)
+            if node.args.kwarg:
+                parameters.append(node.args.kwarg.arg)
+
+            functions.append(
+                FunctionEntry(
+                    name=node.name,
+                    file=file_path,
+                    start_line=node.lineno,
+                    end_line=_end_lineno(node),
+                    parameters=tuple(parameters),
+                    variables_read=tuple(sorted(analyzer.reads)),
+                    variables_written=tuple(sorted(analyzer.writes)),
+                    functions_called=tuple(sorted(analyzer.calls)),
+                    docstring=ast.get_docstring(node),
+                    accesses=tuple(analyzer.accesses),
+                )
+            )
+        elif isinstance(node, ast.ClassDef):
+            class_analyzer = _ClassAnalyzer()
+            for body_node in node.body:
+                class_analyzer.visit(body_node)
+
+            classes.append(
+                ClassEntry(
+                    name=node.name,
+                    file=file_path,
+                    start_line=node.lineno,
+                    end_line=_end_lineno(node),
+                    methods=tuple(sorted(class_analyzer.methods)),
+                    attributes=tuple(sorted(class_analyzer.attributes)),
+                    base_classes=tuple(
+                        sorted(filter(None, (_annotation_to_name(base) for base in node.bases)))
+                    ),
+                    docstring=ast.get_docstring(node),
+                )
+            )
+
+    return ModuleParseResult(
+        file=file_path,
+        functions=tuple(functions),
+        classes=tuple(classes),
+        imports=tuple(imports),
+        assignments=tuple(assignments),
+    )
+
+
+def parse_python_file(path: str | Path) -> ModuleParseResult:
+    """Parse a Python source file from disk."""
+    file_path = Path(path)
+    source = file_path.read_text(encoding="utf-8")
+    return parse_python_source(source, file=file_path)

package/parser/call_resolver.py

@@ -0,0 +1,52 @@
+"""Call resolution utilities for call graph generation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .models import FunctionEntry, ImportEntry, ModuleParseResult
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedCall:
+    """Resolved function call target."""
+
+    caller: str
+    callee: str
+    resolved: bool
+
+
+def _import_alias_map(imports: tuple[ImportEntry, ...]) -> dict[str, str]:
+    mapping: dict[str, str] = {}
+    for entry in imports:
+        if entry.module:
+            for name in entry.names:
+                mapping[name] = f"{entry.module}.{name}"
+        else:
+            for name in entry.names:
+                mapping[name] = name
+    return mapping
+
+
+def resolve_calls(module: ModuleParseResult) -> tuple[ResolvedCall, ...]:
+    """Resolve function call strings using local symbols and import aliases."""
+    local_funcs = {fn.name for fn in module.functions}
+    aliases = _import_alias_map(module.imports)
+
+    resolved_calls: list[ResolvedCall] = []
+    for fn in module.functions:
+        for called in fn.functions_called:
+            if called in local_funcs:
+                resolved_calls.append(ResolvedCall(caller=fn.name, callee=called, resolved=True))
+                continue
+
+            head = called.split(".", 1)[0]
+            if head in aliases:
+                tail = called[len(head) + 1 :] if called.startswith(f"{head}.") else ""
+                normalized = aliases[head]
+                callee = f"{normalized}.{tail}" if tail else normalized
+                resolved_calls.append(ResolvedCall(caller=fn.name, callee=callee, resolved=False))
+            else:
+                resolved_calls.append(ResolvedCall(caller=fn.name, callee=called, resolved=False))
+
+    return tuple(resolved_calls)

package/parser/models.py

@@ -0,0 +1,75 @@
+"""Intermediate representation models emitted by the parser."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class VariableAccess:
+    """Represents a variable read/write access in function scope."""
+
+    name: str
+    line: int
+    access_type: str  # "read" | "write"
+
+
+@dataclass(frozen=True, slots=True)
+class FunctionEntry:
+    """Represents parsed metadata for a function."""
+
+    name: str
+    file: Path
+    start_line: int
+    end_line: int
+    parameters: tuple[str, ...]
+    variables_read: tuple[str, ...]
+    variables_written: tuple[str, ...]
+    functions_called: tuple[str, ...]
+    docstring: str | None
+    accesses: tuple[VariableAccess, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class ClassEntry:
+    """Represents parsed metadata for a class."""
+
+    name: str
+    file: Path
+    start_line: int
+    end_line: int
+    methods: tuple[str, ...]
+    attributes: tuple[str, ...]
+    base_classes: tuple[str, ...]
+    docstring: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class ImportEntry:
+    """Represents an import statement."""
+
+    module: str
+    names: tuple[str, ...]
+    line: int
+
+
+@dataclass(frozen=True, slots=True)
+class AssignmentEntry:
+    """Represents an assignment target at module scope."""
+
+    target: str
+    line: int
+
+
+@dataclass(slots=True)
+class ModuleParseResult:
+    """Top-level parse result for a Python module."""
+
+    file: Path
+    functions: tuple[FunctionEntry, ...] = ()
+    classes: tuple[ClassEntry, ...] = ()
+    imports: tuple[ImportEntry, ...] = ()
+    assignments: tuple[AssignmentEntry, ...] = ()
+    parse_errors: tuple[str, ...] = ()
+    metadata: dict[str, str] = field(default_factory=dict)

package/parser/tree_sitter_adapter.py

@@ -0,0 +1,56 @@
+"""Tree-sitter adapter contract and graceful fallback for parsing."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+from .ast_parser import parse_python_file
+from .models import ModuleParseResult
+
+
+class TreeSitterParser(Protocol):
+    """Protocol for a tree-sitter-backed parser implementation."""
+
+    def parse_file(self, path: Path) -> ModuleParseResult:
+        """Parse a file and return module parse result."""
+
+
+@dataclass(slots=True)
+class ParserFallbackResult:
+    """Result with parser backend metadata."""
+
+    result: ModuleParseResult
+    backend: str
+    fallback_reason: str | None = None
+
+
+def parse_with_fallback(path: str | Path, tree_sitter: TreeSitterParser | None = None) -> ParserFallbackResult:
+    """Use tree-sitter when available, otherwise fallback to stdlib AST parser."""
+    file_path = Path(path)
+
+    if tree_sitter is None:
+        return ParserFallbackResult(
+            result=parse_python_file(file_path),
+            backend="ast",
+            fallback_reason="tree_sitter_unavailable",
+        )
+
+    try:
+        ts_result = tree_sitter.parse_file(file_path)
+    except Exception as exc:  # pragma: no cover - defensive fallback
+        return ParserFallbackResult(
+            result=parse_python_file(file_path),
+            backend="ast",
+            fallback_reason=f"tree_sitter_failed:{exc.__class__.__name__}",
+        )
+
+    if ts_result.parse_errors:
+        return ParserFallbackResult(
+            result=parse_python_file(file_path),
+            backend="ast",
+            fallback_reason="tree_sitter_partial_or_error",
+        )
+
+    return ParserFallbackResult(result=ts_result, backend="tree_sitter")