uce-engine 0.1.0__tar.gz

uce_engine-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: uce-engine
+Version: 0.1.0
+Summary: Unified Context Engine
+Author: UCE Contributors
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: <3.13,>=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: neo4j>=5.14.0
+Requires-Dist: watchdog>=3.0.0
+Requires-Dist: PyYAML>=6.0.1
+Requires-Dist: fastmcp>=0.1.0
+Requires-Dist: tree_sitter==0.20.1
+Requires-Dist: tree_sitter_languages==1.10.2
+
+# Unified Context Engine (UCE)
+
+## What It Does
+UCE is a deterministic semantic governance engine for agentic systems. It builds a Neo4j knowledge graph across code, schema, requirements, policies, APIs, and services, then performs multi-hop reasoning to produce explainable impact analysis and risk scoring.
+
+## Why It Matters
+Traditional RAG is probabilistic and not auditable. UCE provides deterministic, traceable reasoning paths that enterprises can validate before allowing agents to execute changes.
+
+## Architecture Overview
+- File graph and import dependencies
+- Function graph and call edges
+- Table/column schema layer
+- Requirement and policy governance
+- API exposure and service ownership
+- Deterministic risk scoring
+
+## Quick Start
+```
+python ingest/file_graph.py
+python ingest/function_graph.py
+python ingest/db_schema.py
+python ingest/requirements.py
+python ingest/policies.py
+python ingest/api_graph.py
+python -c "from impact import explain_change; print(explain_change('table','meetings'))"
+```
+
+## Example Output
+```json
+{
+  "entity": "meetings",
+  "affected_files": ["app/api/webhook/route.ts"],
+  "affected_functions": ["POST@app/api/webhook/route.ts"],
+  "affected_apis": ["POST /api/webhook"],
+  "affected_services": ["webhook"],
+  "violated_requirements": ["RQ-003"],
+  "enforced_policies": ["P-001"],
+  "risk_breakdown": {
+    "backend_files": 1,
+    "violated_requirements": 1,
+    "enforced_policies": 1,
+    "affected_apis": 1,
+    "risk_score": 15
+  },
+  "risk_score": 15,
+  "trace_paths": [
+    "Table meetings -> File app/api/webhook/route.ts -> Function POST -> API POST /api/webhook -> Service webhook",
+    "Table meetings -> Requirement RQ-003 -> Policy P-001"
+  ]
+}
+```
+
+## Risk Model
+```
+risk_score =
+  2 * backend_files
+  4 * violated_requirements
+  6 * enforced_policies
+  3 * affected_apis
+```
+
+## Roadmap
+1. Cross-repository dependency linking
+2. Temporal graph snapshots
+3. CI integration for pre-merge governance
+4. Schema change impact automation
+
+## License
+Apache 2.0

uce_engine-0.1.0/README.md

@@ -0,0 +1,69 @@
+# Unified Context Engine (UCE)
+
+## What It Does
+UCE is a deterministic semantic governance engine for agentic systems. It builds a Neo4j knowledge graph across code, schema, requirements, policies, APIs, and services, then performs multi-hop reasoning to produce explainable impact analysis and risk scoring.
+
+## Why It Matters
+Traditional RAG is probabilistic and not auditable. UCE provides deterministic, traceable reasoning paths that enterprises can validate before allowing agents to execute changes.
+
+## Architecture Overview
+- File graph and import dependencies
+- Function graph and call edges
+- Table/column schema layer
+- Requirement and policy governance
+- API exposure and service ownership
+- Deterministic risk scoring
+
+## Quick Start
+```
+python ingest/file_graph.py
+python ingest/function_graph.py
+python ingest/db_schema.py
+python ingest/requirements.py
+python ingest/policies.py
+python ingest/api_graph.py
+python -c "from impact import explain_change; print(explain_change('table','meetings'))"
+```
+
+## Example Output
+```json
+{
+  "entity": "meetings",
+  "affected_files": ["app/api/webhook/route.ts"],
+  "affected_functions": ["POST@app/api/webhook/route.ts"],
+  "affected_apis": ["POST /api/webhook"],
+  "affected_services": ["webhook"],
+  "violated_requirements": ["RQ-003"],
+  "enforced_policies": ["P-001"],
+  "risk_breakdown": {
+    "backend_files": 1,
+    "violated_requirements": 1,
+    "enforced_policies": 1,
+    "affected_apis": 1,
+    "risk_score": 15
+  },
+  "risk_score": 15,
+  "trace_paths": [
+    "Table meetings -> File app/api/webhook/route.ts -> Function POST -> API POST /api/webhook -> Service webhook",
+    "Table meetings -> Requirement RQ-003 -> Policy P-001"
+  ]
+}
+```
+
+## Risk Model
+```
+risk_score =
+  2 * backend_files
+  4 * violated_requirements
+  6 * enforced_policies
+  3 * affected_apis
+```
+
+## Roadmap
+1. Cross-repository dependency linking
+2. Temporal graph snapshots
+3. CI integration for pre-merge governance
+4. Schema change impact automation
+
+## License
+Apache 2.0

uce_engine-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "uce-engine"
+version = "0.1.0"
+description = "Unified Context Engine"
+readme = "README.md"
+requires-python = ">=3.10,<3.13"
+license = {text = "MIT"}
+authors = [{name = "UCE Contributors"}]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+]
+dependencies = [
+  "neo4j>=5.14.0",
+  "watchdog>=3.0.0",
+  "PyYAML>=6.0.1",
+  "fastmcp>=0.1.0",
+  "tree_sitter==0.20.1",
+  "tree_sitter_languages==1.10.2",
+]
+
+[project.scripts]
+uce = "uce.run:main"
+
+[tool.setuptools.packages.find]
+include = ["uce*"]

uce_engine-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

uce_engine-0.1.0/uce/__init__.py

@@ -0,0 +1,3 @@
+from uce.run import run_uce
+
+__all__ = ["run_uce"]

uce_engine-0.1.0/uce/core/__init__.py

@@ -0,0 +1 @@
+

uce_engine-0.1.0/uce/core/config.py

@@ -0,0 +1,103 @@
+import os
+from dataclasses import dataclass
+from typing import Any
+
+try:
+    import yaml
+except ImportError as exc:  # pragma: no cover - explicit runtime guidance
+    raise ImportError(
+        "PyYAML is required. Install with `pip install pyyaml`."
+    ) from exc
+
+
+@dataclass(frozen=True)
+class Neo4jConfig:
+    uri: str
+    user: str
+    password: str
+
+
+@dataclass(frozen=True)
+class PathsConfig:
+    code: tuple[str, ...]
+    schema: tuple[str, ...]
+    requirements: tuple[str, ...]
+    policies: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class UceConfig:
+    project_root: str
+    languages: tuple[str, ...]
+    paths: PathsConfig
+    ignore: tuple[str, ...]
+    aliases: dict[str, str]
+    neo4j: Neo4jConfig
+
+
+def _as_tuple(value: Any) -> tuple[str, ...]:
+    if value is None:
+        return tuple()
+    if isinstance(value, (list, tuple)):
+        return tuple(str(v) for v in value if v is not None)
+    return (str(value),)
+
+
+def _normalize_path(root: str, path: str) -> str:
+    joined = os.path.abspath(os.path.join(root, path))
+    return os.path.normpath(joined)
+
+
+def load_config(config_path: str, project_root_override: str | None = None) -> UceConfig:
+    if not os.path.exists(config_path):
+        raise FileNotFoundError(f"Config not found: {config_path}")
+
+    with open(config_path, "r", encoding="utf-8") as handle:
+        raw = yaml.safe_load(handle) or {}
+
+    project_root = project_root_override or raw.get("project_root") or "."
+    project_root = os.path.abspath(project_root)
+
+    languages = _as_tuple(raw.get("languages") or [])
+    languages = tuple(sorted({lang.lower() for lang in languages}))
+
+    paths_raw = raw.get("paths") or {}
+    paths = PathsConfig(
+        code=_as_tuple(paths_raw.get("code") or ["."]),
+        schema=_as_tuple(paths_raw.get("schema") or ["db"]),
+        requirements=_as_tuple(paths_raw.get("requirements") or ["requirements"]),
+        policies=_as_tuple(paths_raw.get("policies") or ["policies"]),
+    )
+
+    ignore = _as_tuple(raw.get("ignore") or [])
+
+    aliases = {str(k): str(v) for k, v in (raw.get("aliases") or {}).items()}
+
+    neo4j_raw = raw.get("neo4j") or {}
+    env_uri = os.getenv("NEO4J_URI")
+    env_user = os.getenv("NEO4J_USER")
+    env_pass = os.getenv("NEO4J_PASSWORD")
+    neo4j = Neo4jConfig(
+        uri=str(env_uri or neo4j_raw.get("uri") or "bolt://localhost:7687"),
+        user=str(env_user or neo4j_raw.get("user") or "neo4j"),
+        password=str(env_pass or neo4j_raw.get("password") or "password"),
+    )
+
+    return UceConfig(
+        project_root=project_root,
+        languages=languages,
+        paths=paths,
+        ignore=ignore,
+        aliases=aliases,
+        neo4j=neo4j,
+    )
+
+
+def resolve_paths(config: UceConfig) -> dict[str, tuple[str, ...]]:
+    root = config.project_root
+    return {
+        "code": tuple(_normalize_path(root, p) for p in config.paths.code),
+        "schema": tuple(_normalize_path(root, p) for p in config.paths.schema),
+        "requirements": tuple(_normalize_path(root, p) for p in config.paths.requirements),
+        "policies": tuple(_normalize_path(root, p) for p in config.paths.policies),
+    }

uce_engine-0.1.0/uce/core/graph_db.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from neo4j import GraphDatabase
+
+
+class GraphDB:
+    def __init__(self, uri: str, user: str, password: str):
+        self.driver = GraphDatabase.driver(uri, auth=(user, password))
+
+    def close(self) -> None:
+        self.driver.close()
+
+    def run(self, query: str, **params):
+        with self.driver.session() as session:
+            return list(session.run(query, **params))
+
+    def ensure_file(self, path: str) -> None:
+        self.run(
+            "MERGE (f:File {path: $path}) SET f.last_seen = timestamp()",
+            path=path,
+        )
+
+    def clear_file_relationships(self, path: str) -> None:
+        self.run(
+            "MATCH (f:File {path: $path})-[r]->() DELETE r",
+            path=path,
+        )
+        self.run(
+            "MATCH (fn:Function {file_path: $path})-[r]->() DELETE r",
+            path=path,
+        )
+        self.run(
+            "MATCH (c:Class {file_path: $path})-[r]->() DELETE r",
+            path=path,
+        )
+        self.run(
+            "MATCH (m:Method {file_path: $path})-[r]->() DELETE r",
+            path=path,
+        )
+
+    def delete_file(self, path: str) -> None:
+        self.run("MATCH (f:File {path: $path}) DETACH DELETE f", path=path)
+        self.run("MATCH (fn:Function {file_path: $path}) DETACH DELETE fn", path=path)
+        self.run("MATCH (c:Class {file_path: $path}) DETACH DELETE c", path=path)
+        self.run("MATCH (m:Method {file_path: $path}) DETACH DELETE m", path=path)
+
+    def cleanup_orphan_apis(self) -> None:
+        self.run(
+            "MATCH (a:API) WHERE NOT ( ()-[:EXPOSED_AS]->(a) ) DETACH DELETE a"
+        )
+        self.run(
+            "MATCH (s:Service) WHERE NOT ( ()-[:BELONGS_TO]->(s) ) DETACH DELETE s"
+        )
+
+    def cleanup_missing_files(self, known_paths: list[str]) -> None:
+        if not known_paths:
+            return
+        self.run(
+            "MATCH (f:File) WHERE NOT f.path IN $paths DETACH DELETE f",
+            paths=known_paths,
+        )

uce_engine-0.1.0/uce/core/risk_model.py

@@ -0,0 +1,54 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class RiskAssessment:
+    risk_score: int
+    severity: str
+    rationale: str
+
+
+def score_from_counts(
+    affected_files: int,
+    affected_functions: int,
+    affected_apis: int,
+    violated_requirements: int,
+    enforced_policies: int,
+) -> int:
+    return (
+        2 * affected_files
+        + affected_functions
+        + 3 * affected_apis
+        + 4 * violated_requirements
+        + 3 * enforced_policies
+    )
+
+
+def assess_risk(
+    affected_files: int,
+    affected_functions: int,
+    affected_apis: int,
+    violated_requirements: int,
+    enforced_policies: int,
+) -> RiskAssessment:
+    score = score_from_counts(
+        affected_files,
+        affected_functions,
+        affected_apis,
+        violated_requirements,
+        enforced_policies,
+    )
+
+    if score >= 20:
+        severity = "high"
+    elif score >= 8:
+        severity = "moderate"
+    else:
+        severity = "low"
+
+    rationale = (
+        f"files={affected_files}, functions={affected_functions}, apis={affected_apis}, "
+        f"violated_requirements={violated_requirements}, enforced_policies={enforced_policies}"
+    )
+
+    return RiskAssessment(risk_score=score, severity=severity, rationale=rationale)

uce_engine-0.1.0/uce/ingestion/__init__.py

@@ -0,0 +1 @@
+

uce_engine-0.1.0/uce/ingestion/code_parser.py

@@ -0,0 +1,280 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Iterable
+from importlib import metadata
+
+try:
+    from tree_sitter_languages import get_parser
+except ImportError as exc:  # pragma: no cover - explicit runtime guidance
+    raise ImportError(
+        "tree_sitter_languages is required. Install with `pip install tree_sitter_languages`."
+    ) from exc
+
+
+LANGUAGE_BY_EXTENSION = {
+    ".py": "python",
+    ".ts": "typescript",
+    ".tsx": "typescript",
+    ".js": "javascript",
+    ".jsx": "javascript",
+    ".go": "go",
+    ".java": "java",
+    ".c": "c",
+    ".h": "c",
+    ".cpp": "cpp",
+    ".hpp": "cpp",
+    ".cc": "cpp",
+    ".cxx": "cpp",
+}
+
+FUNCTION_NODES = {
+    "function_definition",
+    "function_declaration",
+    "function_item",
+    "function",
+    "function_expression",
+    "function_signature",
+    "arrow_function",
+    "lambda_expression",
+    "function_literal",
+    "method_declaration",
+    "method_definition",
+}
+
+CLASS_NODES = {
+    "class_definition",
+    "class_declaration",
+    "class_specifier",
+    "struct_specifier",
+}
+
+METHOD_NODES = {
+    "method_definition",
+    "method_declaration",
+    "constructor_declaration",
+}
+
+CALL_NODES = {
+    "call_expression",
+    "call",
+    "function_call",
+}
+
+IMPORT_NODES = {
+    "import_statement",
+    "import_from_statement",
+    "import_declaration",
+    "import_clause",
+    "import_spec",
+    "import_specifier",
+    "require_call",
+}
+
+STRING_NODES = {"string", "string_literal", "interpreted_string_literal", "raw_string_literal"}
+IDENTIFIER_NODES = {
+    "identifier",
+    "property_identifier",
+    "type_identifier",
+    "field_identifier",
+}
+
+
+@dataclass(frozen=True)
+class ParsedCode:
+    language: str
+    imports: tuple[str, ...]
+    functions: tuple[str, ...]
+    classes: tuple[str, ...]
+    methods: tuple[tuple[str, str | None], ...]
+    calls: tuple[str, ...]
+
+
+_PARSER_CACHE: dict[str, object] = {}
+_PARSER_ERROR: Exception | None = None
+
+
+def detect_language(path: str) -> str | None:
+    _, ext = os.path.splitext(path)
+    return LANGUAGE_BY_EXTENSION.get(ext.lower())
+
+
+def _node_text(node, source: bytes) -> str:
+    return source[node.start_byte : node.end_byte].decode("utf-8", errors="ignore")
+
+
+def _first_identifier(node, source: bytes) -> str | None:
+    name_node = node.child_by_field_name("name")
+    if name_node is not None:
+        return _node_text(name_node, source)
+
+    for child in node.children:
+        if child.type in IDENTIFIER_NODES:
+            return _node_text(child, source)
+    return None
+
+
+def _last_identifier(node, source: bytes) -> str | None:
+    identifiers = []
+    for child in node.children:
+        if child.type in IDENTIFIER_NODES:
+            identifiers.append(_node_text(child, source))
+    if identifiers:
+        return identifiers[-1]
+    return None
+
+
+def _extract_import(node, source: bytes) -> str | None:
+    for child in node.children:
+        if child.type in STRING_NODES:
+            value = _node_text(child, source)
+            return value.strip("\"'` ")
+
+    for child in node.children:
+        if child.type in IDENTIFIER_NODES:
+            return _node_text(child, source)
+
+    text = _node_text(node, source).strip()
+    return text or None
+
+
+def _extract_call_name(node, source: bytes) -> str | None:
+    target = node.child_by_field_name("function") or node.child_by_field_name("callee")
+    if target is None:
+        target = node
+
+    name = _last_identifier(target, source)
+    if name:
+        return name
+
+    for child in target.children:
+        if child.type in IDENTIFIER_NODES:
+            return _node_text(child, source)
+
+    return None
+
+
+def _walk(node) -> Iterable:
+    yield node
+    for child in node.children:
+        yield from _walk(child)
+
+
+def parse_source(source_bytes: bytes, language: str) -> ParsedCode:
+    parser = _get_parser(language)
+    tree = parser.parse(source_bytes)
+    root = tree.root_node
+
+    imports: set[str] = set()
+    functions: set[str] = set()
+    classes: set[str] = set()
+    methods: set[tuple[str, str | None]] = set()
+    calls: set[str] = set()
+
+    class_stack: list[str] = []
+
+    def visit(node):
+        nonlocal class_stack
+        if node.type in CLASS_NODES:
+            class_name = _first_identifier(node, source_bytes)
+            if class_name:
+                classes.add(class_name)
+                class_stack.append(class_name)
+            for child in node.children:
+                visit(child)
+            if class_name:
+                class_stack.pop()
+            return
+
+        if node.type in METHOD_NODES:
+            method_name = _first_identifier(node, source_bytes)
+            if method_name:
+                methods.add((method_name, class_stack[-1] if class_stack else None))
+            for child in node.children:
+                visit(child)
+            return
+
+        if node.type in FUNCTION_NODES:
+            fn_name = _first_identifier(node, source_bytes)
+            if fn_name:
+                functions.add(fn_name)
+
+        if node.type in CALL_NODES:
+            call_name = _extract_call_name(node, source_bytes)
+            if call_name:
+                calls.add(call_name)
+
+        if node.type in IMPORT_NODES:
+            imported = _extract_import(node, source_bytes)
+            if imported:
+                imports.add(imported)
+
+        for child in node.children:
+            visit(child)
+
+    visit(root)
+
+    return ParsedCode(
+        language=language,
+        imports=tuple(sorted(imports)),
+        functions=tuple(sorted(functions)),
+        classes=tuple(sorted(classes)),
+        methods=tuple(sorted(methods)),
+        calls=tuple(sorted(calls)),
+    )
+
+
+def parse_file(path: str) -> ParsedCode | None:
+    language = detect_language(path)
+    if not language:
+        return None
+    with open(path, "rb") as handle:
+        source_bytes = handle.read()
+    return parse_source(source_bytes, language)
+
+
+def _get_parser(language: str):
+    global _PARSER_ERROR
+    if _PARSER_ERROR is not None:
+        raise RuntimeError(_parser_error_message(_PARSER_ERROR)) from _PARSER_ERROR
+
+    if language in _PARSER_CACHE:
+        return _PARSER_CACHE[language]
+
+    try:
+        parser = get_parser(language)
+    except TypeError as exc:
+        _PARSER_ERROR = exc
+        raise RuntimeError(_parser_error_message(exc)) from exc
+    except Exception as exc:
+        _PARSER_ERROR = exc
+        raise RuntimeError(
+            f"Failed to load tree-sitter parser for '{language}': {exc}"
+        ) from exc
+
+    _PARSER_CACHE[language] = parser
+    return parser
+
+
+def validate_languages(languages: Iterable[str]) -> None:
+    for lang in sorted({lang for lang in languages if lang}):
+        _get_parser(lang)
+
+
+def _parser_error_message(exc: Exception) -> str:
+    try:
+        ts_version = metadata.version("tree_sitter")
+    except Exception:
+        ts_version = "unknown"
+    try:
+        tsl_version = metadata.version("tree_sitter_languages")
+    except Exception:
+        tsl_version = "unknown"
+
+    return (
+        "Tree-sitter parser load failed due to an incompatibility between "
+        f"tree_sitter ({ts_version}) and tree_sitter_languages ({tsl_version}). "
+        "Install a compatible pair, for example `pip install tree_sitter==0.20.1` "
+        "or upgrade tree_sitter_languages to match your tree_sitter version."
+    )