Metadata-Version: 2.4
Name: uce-engine
Version: 0.1.3
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
- **Python 3.10+** (recommended: 3.10 on Windows due to Tree-sitter wheels)
- **Neo4j** running locally or remotely

### Neo4j Setup (Local)
1. Install Neo4j Desktop or Neo4j Server.
2. Start a database and note the Bolt URI (default: `bolt://localhost:7687`).
3. Set a username and password.

### Neo4j Setup (Docker)
```bash
docker run --name neo4j-uce -p7474:7474 -p7687:7687 \
  -e NEO4J_AUTH=neo4j/testpassword \
  neo4j:5
```

## Install
```bash
pip install uce-engine
```

## Configure
Create a `config.yaml` file in any folder (recommended in the repo you want to analyze).

Example:
```yaml
project_root: ../talkai-main/

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

paths:
  code:
    - src
  schema:
    - src/db
  requirements:
    - src/requirements
  policies:
    - src/policies

ignore:
  - .git
  - .next
  - __pycache__
  - node_modules
  - venv
  - dist
  - build
  - coverage
  - .idea
  - .vscode
  - ui
  - views
  - public
  - assets
  - styles
  - css
  - scss
  - ".log"

aliases:
  "@/": src/

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

### Optional `.env` (recommended for local development)
UCE can load environment variables from a `.env` file.

Defaults:
- UCE looks for `.env` at the repo root (next to `config.yaml`).
- You can override the location with `UCE_DOTENV_PATH`.

We include a template at `.env.example`. Copy it to `.env` and fill in your values. **Do not commit `.env`** (it contains secrets).

Common variables:
- `NEO4J_URI`, `NEO4J_USERNAME`, `NEO4J_PASSWORD`
- `LLM_PROVIDER`, `OPENAI_API_KEY`
- `NEO4J_TRANSPORT_MODE`, `NEO4J_MCP_HTTP_URL`

### How `ignore` Works
`ignore` entries are **substring path filters** applied to relative file paths. If a file path contains `/ui/` or starts with `ui/`, it will be skipped.

Globs like `"*.log"` are treated as **literal substrings** unless you customize the matcher.

## Run (CLI)
From anywhere:
```bash
uce --config path/to/config.yaml
```

This will:
1. Load configuration
2. Connect to Neo4j
3. Build or update the graph
4. Start the file watcher
5. Launch the MCP server

## Run End-to-End (LLM Ingestion)
If you want LLM-based requirements/policies ingestion, you also need the **Neo4j MCP server** running.

1. Start Neo4j and ensure credentials are correct.
2. Create `.env` from `.env.example` and set:
   - `LLM_PROVIDER`, `OPENAI_API_KEY` (or Anthropic equivalents)
   - `NEO4J_TRANSPORT_MODE=http`
   - `NEO4J_MCP_HTTP_URL=http://127.0.0.1:8000/mcp/`
3. In a separate terminal, start the Neo4j MCP server:
```bash
python neo4j-mcp/server.py --transport http --server-host 127.0.0.1 --server-port 8000 --server-path /mcp/
```
4. Run UCE:
```bash
uce --config path/to/config.yaml
```

### Stdio MCP (optional)
If you prefer stdio, set:
```
NEO4J_TRANSPORT_MODE=stdio
NEO4J_MCP_COMMAND=.../python -u neo4j-mcp/server.py --transport stdio
```
Then run `uce --config ...` without starting the MCP server separately.

## Run (Library)
```python
from uce import run_uce

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

## MCP Tools
UCE exposes reasoning tools via MCP:
- `impact_analysis`
- `explain_change`
- `risk_assessment`

These tools query the graph (no ingestion logic).

## What Nodes Are In The Graph
- `File`
- `Function`
- `Class`
- `Method`
- `Table`
- `Column`
- `Requirement`
- `Policy`

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

## Typical Workflow
1. Install Neo4j and start it.
2. Create `config.yaml` pointing to your repo.
3. Run `uce --config config.yaml`.
4. Query the MCP server or Neo4j to explore the graph.

## Troubleshooting
**Neo4j auth error**
- Verify `neo4j.uri`, `neo4j.user`, `neo4j.password` in `config.yaml`.
- Make sure the database is running.

**APOC missing (schema ingestion error)**
- If you see `There is no procedure with the name apoc.meta.schema`, install the APOC plugin.
- Neo4j Desktop: open your DB → Plugins → install **APOC** → restart the DB.
- Docker: set `NEO4J_PLUGINS='["apoc"]'` and restart the container.

**Tree-sitter parser error on Windows**
- Use Python 3.10 in a clean venv.

**No schema/requirements/policies detected**
- Check `paths.schema`, `paths.requirements`, `paths.policies` in `config.yaml`.

## License
MIT
