Metadata-Version: 2.4
Name: lambdazen-local
Version: 0.1.22
Summary: LambdaZen Local — sync tool for LambdaZen concept repositories
License: Proprietary
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: simplejson>=3.17
Requires-Dist: mcp>=1.0

# LambdaZen Local

**LambdaZen Local** is the official command-line tool for syncing [LambdaZen](https://lambdazen.com) concept repositories to and from your local file system. It works like Git for LambdaZen — clone a concept hierarchy, edit the unpacked files locally, then push your changes back to the cloud.

## Requirements

- Python 3.9 or later
- A LambdaZen account with API access (`LZ_API_KEY` and `LZ_CJS_TOKEN`)

## Installation

```bash
pip install lambdazen-local
```

This installs the `lzlocal` command globally into your Python environment.

---

## Quick Start

```bash
# 1. Save your credentials
lzlocal configure

# 2. Clone a concept repository
lzlocal clone /myuser/myrepo/rootuuid/ ./my-project

# 3. Edit files inside my-project/files/

# 4. Push your changes back to the cloud
lzlocal push ./my-project
```

---

## Credentials

LambdaZen Local needs two credentials to talk to the cloud:

| Variable | Description |
|---|---|
| `LZ_API_KEY` | Your LambdaZen REST API key |
| `LZ_CJS_TOKEN` | Your LambdaZen CJS token |

### Option 1 — `lzlocal configure` (recommended)

Run once per user/environment to save credentials permanently to `~/.lzlocal/.env`.
Credentials are always stored per-user so multiple environments can coexist.

```bash
lzlocal configure
# Prompts:
#   Username (e.g. clouddev, cloudqa): clouddev
#   LZ_API_KEY: ...
#   LZ_CJS_TOKEN: ...
```

Pass values directly to skip interactive prompts:

```bash
lzlocal configure --user clouddev --api-key DEV_KEY --cjs-token DEV_TOKEN
lzlocal configure --user cloudqa  --api-key QA_KEY  --cjs-token QA_TOKEN
```

LambdaZen Local automatically selects the right key based on the user segment in the repository URI — e.g. `/clouddev/myrepo/...` uses `LZ_API_KEY_CLOUDDEV`.

### Option 2 — Environment variables

Set variables in your shell before running any command:

```bash
export LZ_API_KEY=your_api_key
export LZ_CJS_TOKEN=your_cjs_token
lzlocal clone /myuser/myrepo/rootuuid/ ./my-project
```

### Option 3 — `.env` file in the current directory

Create a `.env` file next to where you run `lzlocal`:

```
LZ_API_KEY=your_api_key
LZ_CJS_TOKEN=your_cjs_token
```

**Priority order** (highest wins): real environment variables → `.env` in CWD → `~/.lzlocal/.env`

---

## Project Layout

After cloning, your project directory looks like this:

```
my-project/
  concepts/      ← raw concept JSON files downloaded from the cloud (do not edit)
  files/         ← unpacked, human-readable files (EDIT THESE)
  deps/          ← read-only dependency concepts referenced by your concepts
  concepts.csv   ← index mapping local UUIDs to cloud URIs (do not edit)
  files.csv      ← index mapping file paths to concepts (do not edit)
```

**Only edit files inside `files/`.** The `concepts/`, `deps/`, `concepts.csv`, and `files.csv` entries are managed automatically by `lzlocal`.

---

## Command Reference

### `configure` — Save credentials

```bash
lzlocal configure [--api-key KEY] [--cjs-token TOKEN] [--user USER]
```

| Flag | Description |
|---|---|
| `--user USER` | LambdaZen username / environment (e.g. `clouddev`, `cloudqa`) — prompted if omitted |
| `--api-key KEY` | API key (prompted if omitted) |
| `--cjs-token TOKEN` | CJS token (prompted if omitted) |

---

### `clone` — Clone a repository from the cloud

Downloads a concept hierarchy from the LambdaZen cloud into a new local directory.

```bash
lzlocal clone ROOT_URI CONCEPTS_PATH [--endpoint URL]
```

| Argument | Description |
|---|---|
| `ROOT_URI` | URI of the root concept, e.g. `/myuser/myrepo/rootuuid/` |
| `CONCEPTS_PATH` | Local path for the new project directory (must not exist yet) |
| `--endpoint URL` | LambdaZen cloud endpoint (uses default if omitted) |

**Examples:**

```bash
lzlocal clone /clouddev/myrepo/abc123/ ./my-project
lzlocal clone /clouddev/myrepo/abc123/ ./my-project --endpoint https://custom.lambdazen.com
```

---

### `pull` — Pull latest changes from the cloud

Refreshes all concepts in an existing local project with the latest versions from the cloud. Fails if you have local changes that conflict with incoming cloud changes.

```bash
lzlocal pull CONCEPTS_PATH [--ignore-conflicts] [--endpoint URL]
```

| Flag | Description |
|---|---|
| `--ignore-conflicts` | Overwrite local changes with cloud versions (use with care) |
| `--endpoint URL` | LambdaZen cloud endpoint |

**Examples:**

```bash
lzlocal pull ./my-project
lzlocal pull ./my-project --ignore-conflicts
```

---

### `pull-concept` — Pull a single concept

Downloads one specific concept from the cloud and unpacks it, leaving all other concepts untouched.

```bash
lzlocal pull-concept CONCEPTS_PATH CONCEPT_URI [--endpoint URL]
```

| Argument | Description |
|---|---|
| `CONCEPTS_PATH` | Local path to the project directory |
| `CONCEPT_URI` | Cloud URI of the concept to refresh, e.g. `/myuser/myrepo/uuid/` |

**Example:**

```bash
lzlocal pull-concept ./my-project /clouddev/myrepo/abc123/
```

---

### `push` — Push all local changes to the cloud

Packs modified files back into concept JSONs and uploads all changed concepts. Fails if the cloud has newer versions of the same concepts (conflict detection).

```bash
lzlocal push CONCEPTS_PATH [--ignore-conflicts] [--endpoint URL]
```

| Flag | Description |
|---|---|
| `--ignore-conflicts` | Overwrite cloud versions with local changes (use with care) |
| `--endpoint URL` | LambdaZen cloud endpoint |

**Examples:**

```bash
lzlocal push ./my-project
lzlocal push ./my-project --ignore-conflicts
```

---

### `push-concept` — Push a single concept to the cloud

Packs and uploads one specific concept by its cloud URI, leaving all other concepts untouched.

```bash
lzlocal push-concept CONCEPTS_PATH CONCEPT_URI [--ignore-conflicts] [--endpoint URL]
```

**Example:**

```bash
lzlocal push-concept ./my-project /clouddev/myrepo/abc123/
```

---

### `diff` — Diff local vs cloud

Compares every local concept against the current cloud version and reports what would change if you ran `push`. Does not modify anything.

```bash
lzlocal diff CONCEPTS_PATH [--quiet] [--endpoint URL]
```

| Flag | Description |
|---|---|
| `--quiet` / `-q` | Print only the mismatch count, not the full diff |

**Examples:**

```bash
lzlocal diff ./my-project
lzlocal diff ./my-project --quiet
```

---

### `local-diff` — Diff two local concept directories

Compares two local concept directories against each other. Useful for reviewing changes between a dev and a QA clone of the same repository.

```bash
lzlocal local-diff SOURCE_PATH TARGET_PATH [--quiet] [--reverse]
```

| Flag | Description |
|---|---|
| `--quiet` / `-q` | Print only the mismatch count |
| `--reverse` / `-r` | Swap source and target for the comparison |

**Examples:**

```bash
lzlocal local-diff ./my-project-dev ./my-project-qa
lzlocal local-diff ./my-project-dev ./my-project-qa --quiet
lzlocal local-diff ./my-project-dev ./my-project-qa --reverse
```

---

### `git-diff` — Diff local vs a git repository

Compares a local concept directory against concepts stored in a git repository. Useful when concepts are also tracked in version control.

```bash
lzlocal git-diff CONCEPTS_PATH GIT_PATH [--quiet] [--reverse]
```

| Flag | Description |
|---|---|
| `--quiet` / `-q` | Print only the mismatch count |
| `--reverse` / `-r` | Swap diff direction |

**Example:**

```bash
lzlocal git-diff ./my-project ./my-git-repo
```

---

### `unpack` — Unpack concept JSONs to files (advanced)

Re-runs the unpack step that converts raw concept JSONs in `concepts/` into the editable files in `files/`. Normally called automatically by `pull` and `pull-concept`.

```bash
lzlocal unpack CONCEPTS_DIR [--ignore-conflicts]
```

---

### `pack` — Pack files back into concept JSONs (advanced)

Re-runs the pack step that reads edited files in `files/` and writes them back into the concept JSONs in `concepts/`. Normally called automatically by `push`.

```bash
lzlocal pack CONCEPTS_DIR [--ignore-conflicts] [--endpoint URL]
```

---

### `upload-concept` — Upload a single concept JSON file (debugging)

Uploads a raw concept JSON file directly to the cloud. Intended for debugging.

```bash
lzlocal upload-concept FILENAME --repo REPO_URI [--endpoint URL]
```

---

## Typical Workflows

### Start a new project

```bash
lzlocal configure                                      # one-time credential setup
lzlocal clone /clouddev/myrepo/rootuuid/ ./my-project  # download from cloud
cd my-project/files
# ... edit files ...
lzlocal push ../                                       # push changes back
```

### Daily sync cycle

```bash
lzlocal diff ./my-project                  # check what's changed
lzlocal pull ./my-project                  # get latest from cloud
# ... make edits in my-project/files/ ...
lzlocal diff ./my-project                  # review your changes before pushing
lzlocal push ./my-project                  # upload to cloud
```

### Refresh a single concept without pulling everything

```bash
lzlocal pull-concept ./my-project /clouddev/myrepo/someuuid/
```

### Compare dev and QA environments

```bash
lzlocal clone /clouddev/myrepo/rootuuid/ ./project-dev
lzlocal clone /cloudqa/myrepo/rootuuid/  ./project-qa
lzlocal local-diff ./project-dev ./project-qa
```

---

## MCP Server

LambdaZen Local ships an MCP (Model Context Protocol) server that exposes LambdaZen indexes and concept operations to AI assistants such as Claude Code.

### Starting the MCP server

**pip:**
```bash
lzlocal-mcp /path/to/concepts
```

**Windows EXE:**
```
LambdaZenLocal.exe mcp /path/to/concepts
```

### MCP Tools

All tools are discoverable via `tools/list` and invoked via `tools/call`.

| MCP Method | Purpose |
|---|---|
| `tools/list` | Discover available tools |
| `tools/call` | Invoke a tool by name with parameters |

| Tool | Description |
|---|---|
| `list_index_types` | List all available LambdaZen index types with their names and cloud URIs |
| `get_index_schema` | Fetch the Elasticsearch field schema of an index type |
| `search_index` | Execute an Elasticsearch query against an index type |
| `get_concept_definition` | Fetch the raw definition JSON of a concept |
| `create_concept` | Create a new concept under a parent folder (two-step: POST stub + PUT definition) |
| `update_concept` | Update an existing concept (full PUT replacement) |
| `get_help_page` | Retrieve embedded help documentation for a concept |
| `get_concept_logs` | Fetch execution logs for a concept (supports keyword and time range filters) |
| `get_control_register` | Fetch the control register for a user |
| `eval_concept_value` | Evaluate a concept node via the eval server |
| `eval_concept_cast` | Evaluate a concept cast to a specific ISA type |
| `eval_concept_tree` | Traverse a concept's full ISA relationship tree |

### MCP Resources

Resources are read-only, URI-addressed data sources. All six are resource templates and expose the following MCP protocol methods:

| MCP Method | Purpose |
|---|---|
| `resources/templates/list` | Discover available resource templates |
| `resources/read` | Fetch resource content by providing the full URI |

| URI Template | Name | Description | MIME Type |
|---|---|---|---|
| `def://<concept-uri>` | Concept Definition | Raw definition JSON of the concept | `application/json` |
| `val://<concept-uri>` | Concept Value | Value of the concept from the eval server | `application/json` |
| `cast://<concept-uri>::<cast-uri>` | Concept Value Cast | Value cast to another concept via is-a relationships | `application/json` |
| `help://<concept-uri>` | Concept Help | Help documentation from the concept's `Help:` child | `text/plain` |
| `logs://<concept-uri>` | Concept Logs | All execution logs, unfiltered | `application/json` |
| `controls://<user>` | Concept Controls | Control register JSON for a user | `application/json` |

**Notes:**
- `cast://` uses `::` as separator because both URIs contain forward slashes. Example: `cast:///clouddev/playground/XYZ123/::/common/core/ABC/`
- For filtered log access (keyword, time range), use the `get_concept_logs` tool instead of the `logs://` resource.

---

## Conflict Handling

LambdaZen Local detects conflicts in two directions:

- **Pull conflicts** — the cloud has a newer version of a concept that you have also modified locally. Use `--ignore-conflicts` to overwrite your local changes with the cloud version.
- **Push conflicts** — the cloud has a newer version of a concept than the one you started from. Use `--ignore-conflicts` to force-overwrite the cloud with your local version.

When a conflict is detected, the command exits with a non-zero status and prints the affected URIs. Resolve by either discarding one side, or using `--ignore-conflicts` deliberately.

---

## License

Proprietary — © LambdaZen Technology Corp. All rights reserved.
