Metadata-Version: 2.5
Name: flowjet
Version: 2.0.3
Summary: FlowJet — agent CLI (fj) and server (ACP + OpenAI-compatible HTTP) powered by soothe-nano
Project-URL: Homepage, https://github.com/caesar0301/flowjet
Project-URL: Repository, https://github.com/caesar0301/flowjet
Project-URL: Issues, https://github.com/caesar0301/flowjet/issues
Author: Xiaming Chen
License: MIT
License-File: LICENSE
Keywords: acp,agent,ai,cli,coding-agent,fj,flowjet,nano,openai,server,soothe
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.15,>=3.11
Requires-Dist: soothe-nano<1.3.0,>=1.2.28
Requires-Dist: soothe<2.0.0,>=1.0.12
Provides-Extra: dev
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: openai>=2.51.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.12.0; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Provides-Extra: server
Requires-Dist: agent-client-protocol[http]<1.0.0,>=0.12.1; extra == 'server'
Requires-Dist: fastapi>=0.115.0; extra == 'server'
Requires-Dist: langchain-core>=0.3; extra == 'server'
Requires-Dist: pydantic-settings>=2.0; extra == 'server'
Requires-Dist: pydantic>=2.0; extra == 'server'
Requires-Dist: uvicorn[standard]>=0.32.0; extra == 'server'
Description-Content-Type: text/markdown

# FlowJet

[![PyPI version](https://img.shields.io/pypi/v/flowjet.svg)](https://pypi.org/p/flowjet)
[![Python versions](https://img.shields.io/pypi/pyversions/flowjet.svg)](https://pypi.org/p/flowjet)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**FlowJet** is a coding agent you can run two ways:

- **`fj`** — ask a question in your terminal, get an answer. No UI, no context-switching.
- **`flowjet-server`** — the same agent as a service: **ACP** over WebSocket and an **OpenAI-compatible HTTP API**, so any OpenAI SDK can drive it.

It runs on [soothe-nano](https://github.com/mirasoth/soothe-nano) — tools, skills, MCP, subagents — with SQLite persistence, so every conversation is resumable.

---

## Install

```bash
pip install flowjet              # CLI
pip install 'flowjet[server]'    # CLI + HTTP service
```

Requires Python 3.11+. The server is an optional extra — installing just `flowjet` pulls a single runtime dependency.

## Configure

```bash
fj setup                         # guided: pick a local or hosted model
# or, with no config file at all:
export OPENAI_API_KEY=sk-...
fj summarize README.md
```

`fj setup` writes `~/.soothe/config/nano.yml`. Without it, FlowJet falls back to `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`.

Not sure your machine is ready? `fj doctor` (add `--deep`, `--live-llm`).

### Backends

Two runtimes can build the agent; they are switched independently per surface:

| Env var | Surface | Default | Values |
|---------|---------|---------|--------|
| `FLOWJET_BACKEND` | CLI (`fj`) | `soothe` | `soothe`, `nano` |
| `FLOWJET_SERVER_BACKEND` | `flowjet-server` / `fj serve` | `nano` | `soothe`, `nano` |

`soothe` is the host runtime (extra middleware and tools over the same
soothe-nano engine). The server defaults to `nano` because it needs a dual-mode
agent — AGENT and ASK graphs selected per request — which `soothe` does not
expose yet; on `soothe` the server builds one host agent per mode instead.

---

## CLI

```bash
fj explain this repo
fj -f and now add tests          # continue this project's latest conversation
fjf what did we decide?          # short alias of fj -f
fj -l                            # list recent conversations
```

| Flag | Meaning |
|------|---------|
| `-f` / `--follow` | Continue the latest thread in this project |
| `-t ID` / `--thread` | Continue (or pin) a specific thread — overrides `-f` |
| `-l` / `--list` | List recent threads (newest first) |
| `-n NUM` | How many threads `-l` shows (`0` = all) |
| `-a` / `--ask` | Read-only: answer without touching files |
| `-v` / `--verbose` | Mirror tool calls on stderr |
| `-c PATH` / `-w DIR` | Alternate `nano.yml` / workspace root |

`-f` is scoped to your current project, so work in other checkouts never hijacks your thread.

Enable shell completion (predicts full queries, not just flags):

```bash
eval "$(fj completion zsh)"      # or: fj completion bash
```

---

## Server

```bash
flowjet-server                   # host :: (dual-stack), port 8618
fj serve --port 8618             # same, from the CLI
```

```python
from openai import OpenAI

client = OpenAI(api_key="local", base_url="http://127.0.0.1:8618/v1")
print(client.responses.create(model="default", input="Hello"))
```

| Endpoint | Purpose |
|----------|---------|
| `POST /v1/responses` | Create a response (`stream=true` → SSE) |
| `GET` / `DELETE /v1/responses/{id}` | Retrieve / cancel |
| `POST /v1/chat/completions` | Chat Completions (non-stream + SSE) |
| `GET /v1/models` | Model ids |
| `GET /health` | Liveness |
| `WS /acp` | Agent Client Protocol |

Per-request options go in `extra_body.flowjet`:

| Field | Values | Meaning |
|-------|--------|---------|
| `session` | string | Isolates workspace + conversation thread |
| `interaction_mode` | `agent` (default) \| `ask` | `ask` is hard read-only |
| `projection` | `report` \| `progress` \| `developer` | How much SSE detail to expose |

Full configuration, environment variables and the security model: [docs/server.md](docs/server.md) · deployment: [deploy/README.md](deploy/README.md).

---

## Extend

Add skills and MCP servers in `nano.yml`:

```yaml
skills:
  - ~/.soothe/skills/my-reviewer

mcp_servers:
  - name: filesystem
    transport: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
```

Skills are `SKILL.md` files loaded on demand; MCP tools activate on demand by default (`defer: true`).

---

## Development

```bash
git clone https://github.com/caesar0301/flowjet.git
cd flowjet
make sync-dev && make test && make lint
```

## Upgrading from 1.x

Version 2.0 merges the former `flowjet-server` project into this one. The distribution is now `flowjet` and import paths changed. See [docs/upgrade.md](docs/upgrade.md).

## License

MIT
