Metadata-Version: 2.4
Name: uce-engine
Version: 0.1.5
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: mcp>=0.1.0
Requires-Dist: anthropic>=0.25.0
Requires-Dist: openai>=1.0.0
Requires-Dist: tree_sitter==0.20.4
Requires-Dist: tree_sitter_languages==1.10.2
Requires-Dist: pydantic>=2.0.0
Requires-Dist: starlette>=0.36.0
Requires-Dist: tiktoken>=0.5.0

# 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
```bash
pip install uce-engine
```

### 2. Create `config.yaml`
Create `config.yaml` in the repo you want to analyze.

Example:
```yaml
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:
```bash
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
```env
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
```bash
neo4j-mcp --transport http --server-host 127.0.0.1 --server-port 8000 --server-path /mcp/
```

### 3. Run UCE
```bash
uce --config path/to/config.yaml
```

### Stdio MCP (optional)
If you prefer stdio, set:
```env
NEO4J_TRANSPORT_MODE=stdio
NEO4J_MCP_COMMAND=neo4j-mcp --transport stdio
```
Then run `uce --config path/to/config.yaml`.

## Run (Library)
```python
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
