Metadata-Version: 2.4
Name: flowgraphapp
Version: 0.2.89
Summary: FlowGraph — local-first knowledge-graph canvas + AI planner, run securely on your own machine.
Project-URL: Homepage, https://flow-graph.com
Author: Naveen
License: FlowGraph — Proprietary License
        Copyright (c) 2026 Naveen. All rights reserved.
        
        This software and its source code (the "Software") are the confidential and
        proprietary property of the copyright holder. No license, right, or permission
        is granted to any person to use, copy, modify, merge, publish, distribute,
        sublicense, sell, or create derivative works of the Software, in whole or in
        part, without the prior written consent of the copyright holder.
        
        Unauthorized copying, distribution, or use of the Software, via any medium, is
        strictly prohibited.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
        FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
        COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER
        IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN
        CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
License-File: LICENSE
Keywords: ai,canvas,graph,knowledge-graph,local-first,planner
Classifier: Environment :: Web Environment
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business
Requires-Python: >=3.9
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.27
Requires-Dist: keyring>=25.0
Requires-Dist: packaging>=23.0
Requires-Dist: platformdirs>=4.2
Requires-Dist: truststore>=0.10.4; python_version >= '3.10'
Requires-Dist: typer>=0.12
Requires-Dist: uvicorn[standard]>=0.30
Requires-Dist: websockets<17,>=13
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Provides-Extra: local-embeddings
Description-Content-Type: text/markdown

# FlowGraph — local server (`flowgraphapp`)

Run FlowGraph — the local-first knowledge-graph canvas + AI planner — on your own
machine. Same app as [flow-graph.com](https://flow-graph.com), served from a hardened
localhost server; your data stays in your browser, and (optionally) your AI key stays
in your OS keychain instead of the browser.

## Install

**From PyPI:**

```bash
python3 -m pip install flowgraphapp      # or, isolated: pipx install flowgraphapp
flowgraph                              # serves http://127.0.0.1:8765 and opens your browser
```

If your shell has a `pip` command, `pip install flowgraphapp` is equivalent. The PyPI
distribution is named `flowgraphapp`; the installed command is `flowgraph`, not
`flowgraphapp`.

FlowGraph pins `websockets>=13,<17`. The local server gets WebSocket support from
`uvicorn[standard]`, while this shared range also remains compatible with `google-genai`; installing
or upgrading FlowGraph must not replace a compatible Google GenAI environment with `websockets 17`.

**From source (developers — the private-repo path, no PyPI needed):**

```bash
# 1. build the frontend once (the server serves app/dist)
cd app && npm run build && cd ..
# 2. install EDITABLE — the `flowgraph` command links back to this repo, so every
#    `git pull` / local edit is live immediately (never reinstall, never publish)
python3 -m pip install -e server/        # or: pipx install -e server/
# 3. run it
flowgraph
```

A plain `pip install server/` (no `-e`) also works but installs a frozen COPY — it goes
stale the moment the repo moves, which is exactly how a `flowgraph` command ends up
missing newer subcommands. Editable is the right mode while developing. The headless
intent runner (`flowgraph run "…"`) resolves `app/scripts/headless-intent.ts` relative to
the repo — automatic under `-e`; a copied install needs `FLOWGRAPH_HEADLESS_ENTRY` set.

Open the printed URL if the browser does not launch automatically. The default port is
`http://127.0.0.1:8765`; if that port is already busy, FlowGraph picks a free port and
prints the replacement URL. Stop with `Ctrl-C`. Options: `flowgraph --port 0`
(auto-pick a free port), `--no-open` (don't open the browser), `flowgraph --help`.

## Why local

- **Offline / air-gapped** — no Cloudflare, no network required for the app itself.
- **Privacy / data locality** — your graph lives in the browser's IndexedDB on this machine.
- **On-device models** — point at Ollama / LM Studio for zero-key, zero-cost AI.
- **No size ceiling** — not bound by hosting per-file limits as the app grows.

## AI

Local-model-first: if a local runtime (Ollama `:11434`, LM Studio `:1234`) is reachable,
it's used with **no key**. Otherwise bring your own provider key — stored in the OS
keychain, used server-side, **never sent to the browser**:

```bash
flowgraph keys set anthropic     # or openrouter / openai / google / deepseek
flowgraph keys list              # shows source, never the key
```

The cross-product map of ordinary AI, Studio, Voice, image generation, Live work, and Codex-hosted
MCP calls is maintained in **[docs/71-ai-call-inventory.md](../docs/71-ai-call-inventory.md)**.
In particular, an async browser call is not a reload-safe background job, and a Codex registration
does not fund the local app's ordinary assistant calls.

### Live Voice

The pip app's own Voice button requires **each person's OpenAI Platform API key** on that person's
trusted local server. A ChatGPT Plus/Pro subscription is not an API key. Store the key in the OS
keychain and restart FlowGraph:

```bash
flowgraph keys set openai
flowgraph keys list
flowgraph
```

The local server calls OpenAI's Realtime client-secret endpoint and returns only a short-lived
credential to the browser. Do not put a normal OpenAI key into browser storage for the Voice
transport. The in-app Settings → **AI model & keys → OpenAI** field is separate: it configures
ordinary Chat, Compose, Studio mapping, and delegated expert answers.

BIM questions use the already-indexed IFC/Autodesk metadata first. Opening Studio, turning 3D on,
and navigating live geometry are separate, confirmation-gated actions because waking geometry can
be slower and use more device memory; turning 3D off is immediate.

The Realtime model itself understands ordinary spoken requests, answers, and chooses typed
FlowGraph actions. It does not use a deterministic phrase table or require a second model call for
every turn. A second, grounded text-model call happens only when Realtime chooses the expert tool
for a deeper evidence or judgment question. The voice action surface includes Undo/Redo, cards,
sections, checklist actions, groups and nested groups, relationship labels, image/video cards,
review status, themes, lenses, scrolling, canvas navigation, and Studio controls.

If the person explicitly asks Voice to inspect the layout, the browser can send the same Realtime
session one temporary image of the visible Canvas and exact graph structure. It excludes app and
browser chrome, is never triggered automatically after a move, and is not saved in the vault or
transcript.

New user-facing operations become voice-capable by registering one typed `AppAction`; the
Realtime tool catalog is generated from that registry and parity-tested. There is no separate
voice phrase table to keep synchronized. **Approve for me** is the default: reversible governed
workspace edits can run, while deletion, sharing, paid AI, waking heavy geometry, and other
dangerous operations still require exact confirmation. **Ask for approval** asks before every
content write; bounded **Full access** never bypasses destructive confirmation.

This local Voice path is separate from **Codex or a supported ChatGPT Work plugin client →
FlowGraph MCP**. That path uses the person's eligible assistant product and calls FlowGraph's
governed MCP tools; it does not supply an API key to this pip app and it does not fund
flow-graph.com's hosted Voice button. Ordinary ChatGPT Voice does not currently expose plugins.

## Autodesk Construction Cloud / Revit / Navisworks

IFC stays local, private, and free. To sign into Autodesk Construction Cloud from the
pip-installed app—or view/translate `.rvt`, `.nwd`, `.dwg`, or `.dgn`—connect your own Autodesk
APS app once:

```bash
# 1. At https://aps.autodesk.com/myapps create a Traditional Web App and add:
#    http://127.0.0.1:8765/api/aps/auth/callback
#
# 2. Store its Client ID + Secret in the OS keychain (input is hidden):
flowgraph keys set aps-client-id
flowgraph keys set aps-client-secret

# 3. Start/restart FlowGraph on the callback's default port:
flowgraph
```

In FlowGraph, add a **Smart 3D** card → **Choose from Autodesk** → complete Autodesk's sign-in
page → choose the ACC project, folder, and model for that card. Each card retains its exact model
version. Autodesk access/refresh tokens and the app secret stay in the local server process and
are never returned to browser JavaScript. `APS_CLIENT_ID` / `APS_CLIENT_SECRET` environment
variables are also supported. Keep port `8765` available because OAuth callback URLs are
port-specific.

## MCP tools (live execution)

The app's Agent view can execute action steps against **your** MCP servers — allowlisted,
deny-by-default, configured server-side only (the browser never holds a session or a
secret). Create `mcp-servers.json` in the FlowGraph config dir (macOS
`~/Library/Application Support/flowgraph/`, Linux `~/.config/flowgraph/`; override with
`FLOWGRAPH_MCP_CONFIG=/path/to/file.json`):

```json
{
  "servers": {
    "revit": {
      "kind": "mcp", "transport": "stdio",
      "command": "python3", "args": ["-m", "revit_mcp_server"],
      "env": { "REVIT_TOKEN": "…" },
      "tools": ["export_ifc", "list_levels"],
      "timeoutMs": 60000
    }
  },
  "limits": { "callTimeoutMs": 30000, "maxResponseBytes": 262144 }
}
```

Only named servers run, and only their named `tools` (or `"*"`) are discoverable/callable.
Every call is timeout-bound and size-capped; a duplicate of the same pending run is refused
(idempotency); config secrets are never echoed in any response. Each server is spawned with
a **minimal environment** (PATH/HOME/locale + the entry's own `env`) — API keys in your
shell are never inherited by MCP subprocesses — and a server that fails or hangs during
startup is killed on the spot, never orphaned. `executed:true` in the
app means a genuine `tools/call` completed here — nothing else can flip a run to LIVE.
Transport is stdio in this version.

This section describes FlowGraph acting as an **MCP client** for tools such as Revit. FlowGraph
also ships its own 47-tool **MCP server** for external agents (governed graph writes plus one
ephemeral, confirmation-gated live-viewer control). The pip wheel bundles it;
Node.js 20 or newer is the only additional runtime requirement:

```bash
flowgraph mcp                         # managed workspace shared with the local app
flowgraph mcp --vault /path/to/vault # optional explicit folder
flowgraph plugin --install           # install the bundled FlowGraph plugin into Codex
```

Its generated catalog is [`../docs/api.md`](../docs/api.md). API v1.2 added the read-only
`get_connection_status` first call: it proves the local folder was paired from the signed-in web
app and gives the account, workspace, and visible canvas names an assistant must match before it
asks to write. The server reads portal mirrors under `canvases/` plus review-gated top-level agent
files. API v1.3 adds `control_3d_viewer`: a render-only relay to the freshest connected local tab,
with explicit confirmation before geometry wakes and a browser-observed result/StepTrace. API
v1.4 adds `request_assistant_connection`, the non-mutating recovery call that can open the local
pairing guide and wait briefly after an unconnected first check.
API v1.5 adds `ifc_model_network`, the bounded data-only projection shared with Model Studio, plus
the Source property / Mapping rule / Required answer path. Its defaults follow the source:
Revit Level / Room or Space / Revit Category / Revit Family / Revit Type for Revit/Navisworks;
IFC Storey / IFC Space / IFC Class / IFC Type / IFC Instance for IFC. It reads explicit authored
Room/Space properties and IFC `IfcSpace` containment, keeps Trade unknown until a labeled mapping
exists, and never wakes geometry.
API v1.6 adds the five pairing-gated write-up visual request tools. The local app may queue a
paragraph and optional direction; an active Codex task can claim it, use an available image
capability, and submit a bounded PNG/JPEG/WebP candidate. The passive MCP server does not start a
Codex turn, registration alone does not prove ImageGen availability, and no subscription credential
enters the browser. Append/Replace remains a separate human action through FlowGraph's governed
write-up patch boundary.

In the local app, Settings → **Connect an AI assistant** offers separate approvals to mirror the
workspace and to register the installed command with Codex. A registration is reported as
**ready** only when the current immutable account also has a non-empty mirror whose observed
portal-canvas count matches its receipt. After that explicit approval, durable local saves refresh
the portal-owned copies while preserving the connection id and all Review Inbox drafts. The local
app polls only that account's managed Review Inbox and offers **Review changes** through its existing
governed import preview; MCP writes never silently merge. The Live Canvas MCP App uses a private
connection capability to frame a read-only production renderer even when Codex has no local-app
cookie; the capability can read only the framed canvas route and cannot reach mutation APIs. Start a
new Codex task afterward so it reloads the tool catalog, then ask it to list the canvases and
compare the names/count with the open app. Existing Codex MCP entries are never overwritten.
Claude and other clients can use the same command, but their registration is client-specific. The
hosted/local Voice buttons are fully separate from that connector. A remote OAuth connector would
replace this note only after its installation and signed-in pairing have been replayed end to end.

## Security (safe by default)

Binds **loopback only** (`127.0.0.1`); a per-session token is required (delivered via the
terminal + a `0600` file; the auto-opened URL carries a one-time ticket, never the token).
Host-header allow-listing blocks DNS-rebinding from websites you visit; Origin checks,
strict CSP, and security headers apply to every route. Exposing beyond loopback
(`--allow-lan`) requires TLS. See `docs/18-local-server.md` for the full threat model.

## Updates

`pip install -U flowgraphapp` (or `flowgraph upgrade`) updates the app and server together;
your data is untouched. A calm one-line "update available" notice appears at startup —
disable with `FLOWGRAPH_NO_UPDATE_CHECK=1`.

## What is in the package

The PyPI wheel contains the local server, compiled FlowGraph web app, governed MCP server, and
installable local FlowGraph universal-plugin package. It does not
include the repo's private planning docs, reference folders, tests, app source tree, or
development scripts.
