uce-engine 0.1.5

Unified Context Engine

Unified Context Engine (UCE)

UCE builds a deterministic knowledge graph of a codebase in Neo4j and exposes reasoning tools over that graph. It works across repositories, supports multiple languages, and continuously updates when files change.

This package is pip-installable and CLI-friendly.

What UCE Does

• Ingests source code, schema, requirements, and policies into a Neo4j graph.
• Tracks files, functions, classes, methods, tables, columns, requirements, and policies.
• Provides deterministic impact analysis and risk assessment.
• Keeps the graph up-to-date via a file watcher.
• Exposes reasoning tools through an MCP server.

Supported Languages

UCE uses Tree-sitter and supports:

• Python
• TypeScript
• JavaScript
• Go
• Java
• C
• C++

Prerequisites

1. Install Python 3.10+. On Windows, Python 3.10 is recommended for Tree-sitter wheels.
2. Install and start Neo4j Desktop or Neo4j Server.
3. Note your Bolt URI, username, and password. The typical default is bolt://localhost:7687 with user neo4j.

Quickstart (Detailed)

1. Install UCE

pip install uce-engine

2. Create config.yaml

Create config.yaml in the repo you want to analyze.

Example:

project_root: .

languages:
  - python
  - typescript
  - javascript
  - go
  - java
  - c
  - cpp

paths:
  code:
    - core
    - ingestion
    - runtime
    - server
    - reasoning
  schema: []
  requirements:
    - artifacts/requirements
  policies:
    - artifacts/policies
  identifiers: # optional: limit identifier usage indexing to these paths
    - server

ignore:
  - .git
  - .next
  - __pycache__
  - node_modules
  - venv
  - dist
  - build
  - coverage
  - .idea
  - .vscode
  - ui
  - views
  - public
  - assets
  - styles
  - css
  - scss
  - .env
  - .DS_Store
  - ".log"
  - ".tmp"
  - ".bak"
  - ".swp"
  - ".swo"
  - ".pyc"
  - ".class"
  - ".o"
  - ".so"
  - ".dll"
  - ".exe"
  - ".dylib"
  - ".zip"
  - ".tar"
  - ".gz"
  - ".7z"
  - ".rar"

aliases:
  "@/": src/

neo4j:
  uri: bolt://localhost:7687
  user: neo4j
  password: testpassword

3. Understand the key config.yaml fields

• project_root: The root folder for this repository. Relative paths are resolved from here.
• languages: Which language parsers to enable.
• paths.code: One or more folders that contain code.
• paths.code can include multiple folders. Use . if you want to scan the entire repo.
• paths.schema: Schema files or folders (SQL, JSON, YAML, etc.).
• paths.requirements: Folders with requirement docs.
• paths.policies: Folders with policy docs.
• paths.identifiers: Optional list of folders where identifier usage indexing is enabled.
• paths.identifiers can also point at a single file. If empty, identifier indexing is disabled.
• ignore: Substring filters applied to relative paths. If a path contains a token, it is skipped.
• aliases: Import alias mapping for resolving internal imports.
• neo4j.uri, neo4j.user, neo4j.password: Connection settings.

4. Create .env (optional but recommended)

UCE can load environment variables from a .env file.

Defaults:

• UCE looks for .env next to config.yaml.
• You can override this location with UCE_DOTENV_PATH.

Templates:

• In the repo, use .env.example as a starting point.
• When installed from PyPI, the template is bundled at core/.env.example inside the package. Do not commit .env to source control; it contains secrets.

Common variables:

• NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD
• LLM_PROVIDER, OPENAI_API_KEY
• NEO4J_TRANSPORT_MODE, NEO4J_MCP_HTTP_URL

5. Run UCE (CLI)

From anywhere:

uce --config path/to/config.yaml

What happens:

1. Loads configuration.
2. Connects to Neo4j.
3. Builds or updates the graph.
4. Starts the file watcher.
5. Launches the MCP server.

LLM Ingestion (End-to-End)

If you want LLM-based requirements or policies ingestion, you also need the Neo4j MCP server running.

1. Set required .env values

LLM_PROVIDER=openai
OPENAI_API_KEY=your_key_here
NEO4J_TRANSPORT_MODE=http
NEO4J_MCP_HTTP_URL=http://127.0.0.1:8000/mcp/

2. Start the Neo4j MCP server

neo4j-mcp --transport http --server-host 127.0.0.1 --server-port 8000 --server-path /mcp/

3. Run UCE

uce --config path/to/config.yaml

Stdio MCP (optional)

If you prefer stdio, set:

NEO4J_TRANSPORT_MODE=stdio
NEO4J_MCP_COMMAND=neo4j-mcp --transport stdio

Then run uce --config path/to/config.yaml.

Run (Library)

from run import run_uce

run_uce("path/to/config.yaml")

Identifier Indexing (Optional)

If you want identifier usage (variable names, type names, field names) indexed into the graph, set paths.identifiers in config.yaml or UCE_IDENTIFIER_PATHS in .env. If it is empty, identifier indexing is disabled.

MCP Tools

UCE exposes reasoning tools via MCP:

• impact_analysis
• explain_change
• risk_assessment
• count_functions_in_file (AST-lite helper)
• find_identifier_usage (AST-lite helper)

These tools query the graph (no ingestion logic).

What Nodes Are In The Graph

• File
• Function
• Class
• Method
• Table
• Column
• Requirement
• Policy
• Identifier (optional, AST-lite usage index)

If you want additional node types (e.g., Dependencies, Endpoints, Services), add them in ingestion and reasoning layers.

License

MIT