Metadata-Version: 2.4
Name: ltcai
Version: 3.4.1
Summary: Lattice AI v3 local-first AI workspace platform with knowledge graph, vector index, hybrid search, agents, and workspace modes
Author: TaeSoo Park
License-Expression: MIT
Project-URL: Homepage, https://github.com/TaeSooPark-PTS/LatticeAI
Project-URL: Repository, https://github.com/TaeSooPark-PTS/LatticeAI
Project-URL: Documentation, https://github.com/TaeSooPark-PTS/LatticeAI/blob/main/README.md
Project-URL: Issues, https://github.com/TaeSooPark-PTS/LatticeAI/issues
Project-URL: Changelog, https://github.com/TaeSooPark-PTS/LatticeAI/blob/main/docs/CHANGELOG.md
Keywords: ai,llm,mlx,mcp,rag,vscode
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi
Requires-Dist: uvicorn
Requires-Dist: pydantic
Requires-Dist: httpx
Requires-Dist: pillow
Requires-Dist: openai
Requires-Dist: python-docx
Requires-Dist: openpyxl
Requires-Dist: python-pptx
Requires-Dist: python-multipart
Requires-Dist: keyring
Requires-Dist: authlib
Requires-Dist: pdfplumber
Requires-Dist: pypdfium2
Requires-Dist: watchdog
Provides-Extra: local
Requires-Dist: mlx-vlm; extra == "local"
Provides-Extra: voice
Requires-Dist: openai-whisper; extra == "voice"
Requires-Dist: SpeechRecognition; extra == "voice"
Requires-Dist: pydub; extra == "voice"
Provides-Extra: all
Requires-Dist: mlx-vlm; extra == "all"
Requires-Dist: openai-whisper; extra == "all"
Requires-Dist: SpeechRecognition; extra == "all"
Requires-Dist: pydub; extra == "all"
Dynamic: license-file

<div align="center">
  <img src="docs/images/logo.svg" alt="Lattice AI" width="120" />

  # Lattice AI

  **Lattice AI v3 — Local-First AI Workspace Platform.**

  Work across Personal and Organization workspaces with Knowledge Graph,
  Vector Index, Hybrid Search, Native Chat, agents, files, models, and
  Basic / Advanced / Admin modes.
</div>

<div align="center">

[![PyPI version](https://img.shields.io/pypi/v/ltcai?label=PyPI)](https://pypi.org/project/ltcai/)
[![npm version](https://img.shields.io/npm/v/ltcai?label=npm)](https://www.npmjs.com/package/ltcai)
[![VS Code Marketplace](https://vsmarketplacebadges.dev/version-short/parktaesoo.ltcai.svg)](https://marketplace.visualstudio.com/items?itemName=parktaesoo.ltcai)
[![Open VSX](https://img.shields.io/open-vsx/v/parktaesoo/ltcai?label=Open%20VSX)](https://open-vsx.org/extension/parktaesoo/ltcai)
[![GitHub release](https://img.shields.io/github/v/release/TaeSooPark-PTS/LatticeAI?label=GitHub%20release)](https://github.com/TaeSooPark-PTS/LatticeAI/releases)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
[![VS Code extension](https://img.shields.io/badge/VS%20Code-extension-blue?logo=visualstudiocode)](https://marketplace.visualstudio.com/items?itemName=parktaesoo.ltcai)

</div>

![Lattice AI — local-first AI workspace](docs/assets/v3.4.0/home.png)

## Install

Install the local workspace:

```bash
pip install ltcai
```

Add Apple Silicon local model support:

```bash
pip install "ltcai[local]"
```

Install the npm CLI:

```bash
npm install -g ltcai
```

Install the coding extension:

- [VS Code Marketplace: parktaesoo.ltcai](https://marketplace.visualstudio.com/items?itemName=parktaesoo.ltcai)
- [Open VSX: parktaesoo.ltcai](https://open-vsx.org/extension/parktaesoo/ltcai)
- [GitHub Releases](https://github.com/TaeSooPark-PTS/LatticeAI/releases)

## Quick Start

Start the workspace:

```bash
LTCAI
```

Then open:

```text
http://127.0.0.1:4825/app
```

Development checkout:

```bash
npm install
npm run dev
```

Useful validation commands:

```bash
npm run check:python
npm run test:unit
npm run build
```

## What Is Lattice AI?

Lattice AI v3 is a local-first AI workspace platform for people and teams who
want their files, models, graph context, retrieval, and agent workflows in one
place.

- **Primary app shell**: `/app` is the default product experience with Chat,
  Files, Hybrid Search, Knowledge Graph, Memory, Models, Settings, Advanced
  agent/workflow tooling, and Admin areas. Classic pages remain compatibility
  routes only; normal workflows stay in `/app`.
- **Local-first AI Workspace**: work starts on your machine, with local data and
  workspace state by default.
- **AI Pipeline Platform**: plan, execute, review, retry, and replay work across
  local models, cloud models, tools, files, and generated artifacts.
- **Knowledge Graph Platform**: documents, images, screenshots, notes,
  conversations, and decisions become linked entities, relationships, evidence,
  and reusable context.
- **Multi-Agent Workflow Platform**: agents hand off structured context, review
  work, retry with reasons, and keep timelines inspectable.
- **Personal / Organization Workspace**: move between personal work and team
  workspaces with role-aware views and Basic / Advanced / Admin modes.
- **Vector Index and Hybrid Search**: local vector rows are derived from the
  Knowledge Graph and fused with keyword and graph signals.
- **Local Model Management**: choose current multimodal local models with source
  disclosure, hardware-aware recommendations, and cloud fallback options.
- **Community-first workspaces**: Personal and Organization workspaces ship in
  the local product; enterprise SSO/SCIM/governance remain future extensions.

## Why Lattice AI?

Most AI tools split your work across a chat window, a model picker, loose files,
and disconnected automations. Lattice AI keeps those parts together:

- files and conversations become graph context;
- graph context feeds pipelines and coding actions;
- model cards disclose country, company, run mode, internet usage, and model
  identity;
- personal and organization workspaces keep team workflows separate from local
  work;
- multi-agent workflows leave behind replayable plans, reviews, retries, and
  outcomes.

## v3.4.1 Highlights

Lattice AI v3.4.1 is the **runtime completion** release: it makes the v3.4.0
runtime systems verifiably complete and corrects the v3.4.0 overclaims an
implementation audit found. Every item is verified by a **live end-to-end run**
against a booted server (see `docs/assets/v3.4.1/e2e_runtime_log.txt`).

- **Hooks — full lifecycle.** One shared tool-dispatch path fires `pre_tool`/
  `post_tool` across the HTTP, agent, and workflow tool paths (v3.4.0 only fired
  on the HTTP path); workflow hooks fire from both the designer and platform
  paths; the upload pipeline fires granular upload + index hooks; **all 7
  built-in hooks have real runners**, and non-executable hooks are flagged
  `advisory`.
- **Local Agent — real probes.** `online`/`handshake`/`health`/
  `filesystem_access` are no longer hardcoded — they are probed (real filesystem
  write, live graph reachability, derived `mode`, `pid`, handshake latency).
- **Connect Folder — proven end-to-end.** A real local folder is connected,
  indexed, and visible in the Files table, retrieval, and hybrid search.
- **Folder Watch — proven end-to-end + restore.** Creating a file triggers a
  debounced reindex (`watchdog` installed); the watch is restored after restart.

See [RELEASE_NOTES_v3.4.1.md](RELEASE_NOTES_v3.4.1.md) and the evidence-traced
[FEATURE_STATUS.md](FEATURE_STATUS.md).

## v3.4.0 Highlights

Lattice AI v3.4.0 is the **platform completion** release: it closes the remaining
non-enterprise functionality gaps the v3.3.0 honesty audit flagged, so the
local-first workspace is complete and demonstrable end-to-end. Each item below is
runtime-verified on a live server, not only wired in source.

- **Hooks now execute.** A real dispatch engine (`run_hook` / `run_hooks` /
  `fire_hook` + `HookContext` / `HookResult`) runs hooks at genuine lifecycle
  points — agents (pre/post-run), workflows (start/end), tools (pre/post-tool),
  and the upload pipeline. `pre_*` hooks can gate (block) an action; every
  dispatch is recorded to a persisted run log surfaced in the Hooks view.
- **Uploads appear in Files.** Uploaded documents are listed with live ingest →
  index state (`/knowledge-graph/documents`), completing upload → Files →
  Knowledge Graph → Hybrid Search → Chat.
- **Vision (VLM) image input.** The Chat composer accepts images by attach,
  drag-and-drop, or paste, with a preview and a **Vision Enabled / Disabled**
  badge driven by the active model's capability.
- **Run agents from the Agents view.** A Run console (goal + roles → Run / Stop /
  Status / Queue / Logs) executes the multi-agent pipeline locally; it runs
  without a model and fires its pre/post-run hooks.
- **On-device Local Agent + Connect Folder + Folder Watch.** My Computer reports
  the real local-runtime agent status and handshake; folders can be connected and
  watched (debounced reindex on change) through the existing on-device endpoints.
- **Enterprise stays honestly disabled.** SSO, SCIM, DLP, Private VPC, SIEM, and
  enterprise RBAC remain off with honest "not available in this build" states.

See [RELEASE_NOTES_v3.4.0.md](RELEASE_NOTES_v3.4.0.md),
[PLATFORM_COMPLETION_REPORT_v3.4.0.md](PLATFORM_COMPLETION_REPORT_v3.4.0.md), and
the evidence-traced [FEATURE_STATUS.md](FEATURE_STATUS.md).

## v3.3.1 Highlights

Lattice AI v3.3.1 rebuilds the visible `/app` product experience while
preserving the existing local-first runtime. The app now presents Chat, Files,
Search, Knowledge, Memory, Models, Settings, Advanced tooling, and Admin
workflows with clearer navigation and honest live/unavailable states.

- **Visual product rebuild** — compact rail navigation, quieter topbar,
  command-palette search, retrieval readiness footer, and denser controls.
- **Truthful Home dashboard** — backend, model, retrieval, memory, source, and
  trace readiness are derived from real endpoints instead of fabricated counts.
- **Basic / Advanced / Admin navigation** — Basic focuses on core workspace
  workflows; Advanced exposes agents, workflows, skills, hooks, and MCP; Admin
  keeps organization controls separate.
- **Files and Settings clarity** — manual upload is available immediately,
  folder watching is explicitly tied to the desktop local agent, and Settings
  shows backend, agent, model, telemetry, and embedding readiness.
- **Design system refresh** — cooler neutral light/dark tokens, tighter 8px
  radius discipline, compact cards/tables/stats/buttons, and regenerated
  hashed v3 assets.

The v3.2.0 platform remains the feature-complete foundation: multi-agent
collaboration, Agent Registry, Marketplace templates, Workflow Agents,
Autonomous Planning, Long-Term Memory, Skills, Hooks, Tool Registry, MCP
Manager, production embedding profiles, and hash-manifested `/app` assets.
Release audit: [docs/V3_2_AUDIT.md](docs/V3_2_AUDIT.md).

## Screenshots

All screenshots are the v3.4.0 `/app` shell. Live model output (VLM inference,
agent-generated text) requires a loaded local model and is not depicted.

### Home

![Home — local-first workspace at a glance](docs/assets/v3.4.0/home.png)

### Chat with Vision (VLM) image input

![Chat — image attach + Vision Enabled badge](docs/assets/v3.4.0/chat.png)

### Files — uploaded documents + Connect Folder

![Files — uploaded documents with index state](docs/assets/v3.4.0/files.png)

### Run agents from the Agents view

![Agent run — goal, roles, and live timeline logs](docs/assets/v3.4.0/agent-run.png)

### Hooks dispatch + run log

![Hooks — per-hook Run and recent executions](docs/assets/v3.4.0/hooks-dispatch.png)

### Local Agent (on-device runtime)

![My Computer — Local Agent status and handshake](docs/assets/v3.4.0/local-agent.png)

### Knowledge Graph

![Knowledge Graph](docs/assets/v3.4.0/knowledge-graph.png)

## Knowledge Graph Flow

```text
files / documents / images / screenshots / conversations / decisions
  -> multimodal understanding
  -> entity and relationship extraction
  -> evidence and artifact storage
  -> Knowledge Graph update
  -> AI pipeline context
  -> coding actions / analysis / documents / team workflows
```

The graph keeps useful workspace context available even when you change models.

## v3 Backend Retrieval

The v3 backend adds a local-first retrieval stack that combines the Knowledge
Graph, a SQLite vector index, and hybrid result fusion. It preserves existing
graph data while adding derived vector rows that can be rebuilt at any time.

Embedding status: production profiles are exposed through
`GET /api/embeddings/providers`, while `lattice-local-hash-v1` remains a
deterministic fallback for offline indexing and tests. It is never presented as
a production semantic embedding model.

Core API contracts:

- `POST /api/search/hybrid`
- `GET /api/search/keyword?q=...`
- `GET /api/search/vector?q=...`
- `GET /api/graph`
- `GET /api/graph/node?node_id=...`
- `GET /api/graph/relationship`
- `GET /api/index/status`
- `POST /api/index/rebuild`

See [docs/V3_BACKEND_ARCHITECTURE.md](docs/V3_BACKEND_ARCHITECTURE.md) for the
storage model, search model, migration behavior, and API response shape.

## Local Model Policy

Lattice AI recommends current-generation multimodal models for local use and
keeps local model choices explicit.

| Family | Default role | Example recommendation |
| --- | --- | --- |
| Gemma 4 | Default Google multimodal family | `mlx-community/gemma-4-12b-it-4bit` |
| Gemma 4 large | Higher-quality local multimodal work | `mlx-community/gemma-4-31b-it-4bit` |
| Qwen3-VL | Smaller, balanced multimodal options | `mlx-community/Qwen3-VL-4B-Instruct-4bit` |
| Llama 4 | Meta multimodal option | `mlx-community/Llama-4-Scout-17B-16E-Instruct-4bit` |

Every recommended model card shows maker country, maker company, run mode,
internet requirement, and model name. See [MODEL_POLICY.md](MODEL_POLICY.md).

## Architecture

```text
Personal / Organization Workspace
  -> files, chats, screenshots, model choices, workflow events
  -> Knowledge Graph
  -> AI Pipeline
  -> Multi-Agent Workflow
  -> coding actions, documents, analysis, team handoffs
```

Core areas:

- FastAPI local workspace app
- Knowledge Graph storage and graph APIs
- AI pipeline and workflow designer
- Multi-agent handoff, review, retry, and replay records
- Local model management and model recommendation catalog
- VS Code / Cursor / VSCodium extension surface
- Personal and organization workspace boundaries

## Documentation

- [ARCHITECTURE.md](ARCHITECTURE.md) — workspace, graph, pipeline, and model-management overview
- [docs/architecture.md](docs/architecture.md) — full architecture reference
- [PROJECT_PRINCIPLES.md](PROJECT_PRINCIPLES.md) — product principles
- [AI_PHILOSOPHY.md](AI_PHILOSOPHY.md) — how AI is used in the workspace
- [MODEL_POLICY.md](MODEL_POLICY.md) — local model recommendation policy
- [KNOWLEDGE_GRAPH.md](KNOWLEDGE_GRAPH.md) — graph model and behavior
- [docs/MULTI_AGENT_RUNTIME.md](docs/MULTI_AGENT_RUNTIME.md) — multi-agent workflow runtime
- [docs/WORKFLOW_DESIGNER.md](docs/WORKFLOW_DESIGNER.md) — AI pipeline designer
- [docs/REALTIME_COLLABORATION.md](docs/REALTIME_COLLABORATION.md) — realtime workspace events
- [docs/ENTERPRISE.md](docs/ENTERPRISE.md) — organization workspaces and SSO
- [docs/PLUGIN_SDK.md](docs/PLUGIN_SDK.md) — plugin SDK
- [RELEASE_NOTES.md](RELEASE_NOTES.md) and [docs/CHANGELOG.md](docs/CHANGELOG.md)

## Release history

| Version | Theme |
| --- | --- |
| **3.4.1** | Runtime completion — hooks full lifecycle (shared tool dispatch across HTTP/agent/workflow, all built-ins real), Local Agent real probes (no hardcoded readiness), Connect Folder + Folder Watch proven live end-to-end + restore-on-restart; corrects v3.4.0 overclaims |
| 3.4.0 | Platform completion — hooks execution engine, uploads visible in Files, VLM image input, agent run trigger, on-device Local Agent / Connect Folder / Folder Watch; Enterprise stays honestly disabled; refreshed v3.4.0 public assets |
| 3.3.1 | Visual product rebuild — rebuilt `/app` shell, Basic/Advanced/Admin navigation, cooler token palette, compact component system, Home readiness dashboard, Files local-agent truthfulness, Settings runtime status, and v3.3.1 design notes |
| **3.3.0** | Product quality & honesty release — evidence-based feature audit (`FEATURE_STATUS.md`), single-source version truth, working manual document upload in Files, fixed document-generation streaming, truthful Home retrieval status, documented design system (`STYLE_SYSTEM.md`) |
| 3.2.0 | Feature-complete platform — multi-agent collaboration, agent registry, marketplace + templates, workflow agents, autonomous planning, long-term memory + manager, skills/hooks/tool registries, MCP manager, all operable from `/app` |
| 3.1.0 | Mainline platform completion — native `/app` workflows, Classic retired from normal paths, production embedding profiles, AgentRuntime/registries, hashed v3 assets |
| 3.0.1 | Release-blocker remediation — provider-backed embeddings (Hash/MLX/Ollama/OpenAI/Custom), unified AgentRuntime boundary, every v3 surface connected or clearly unavailable |
| 3.0.0 | v3 local-first AI workspace platform — `/app`, Native Chat, Knowledge Graph, Vector Index, Hybrid Search, workspace modes |
| 2.2.7 | Visual system stabilization — cohesive dark/light screens, crisp chat composer, dark graph canvas, Workspace OS polish |
| 2.2.6 | Token-native CSS foundation |
| 2.2.5 | Release hygiene hotfix — dark overlays, modal stack, cache-busting, favicon, and Telegram log masking |
| 2.2.4 | Chat dark-mode completion |
| 2.2.3 | Frontend stability and UX fixes |
| 2.2.2 | Frontend QA stabilization — mobile nav, admin actions, overflow fixes, and expanded visual tests |
| 2.2.1 | Frontend and UX overhaul for responsive workspace, themes, graph UX, admin reflow, and file attachment |
| 2.2.0 | Multimodal-first Knowledge Graph and local model source disclosure |
| 2.1.0 | Multi-agent workflow maturity |
| 2.0.0 | AI pipeline, workflow, and plugin platform foundation |
| 1.7.0 | Graph and collaboration |
| 1.6.0 | Product experience deepening |

## License

MIT
