Metadata-Version: 2.4
Name: fruxon
Version: 0.5.16
Summary: The Fruxon SDK is a lightweight Python client for integrating with the Fruxon platform.
Project-URL: bugs, https://github.com/fruxon-ai/fruxon-sdk/issues
Project-URL: changelog, https://github.com/fruxon-ai/fruxon-sdk/blob/main/HISTORY.md
Project-URL: homepage, https://github.com/fruxon-ai/fruxon-sdk
Author-email: Hagai Cohen <hagai@fruxon.com>
Maintainer-email: Hagai Cohen <hagai@fruxon.com>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: keyring>=24.0
Requires-Dist: typer>=0.13
Provides-Extra: test
Requires-Dist: coverage; extra == 'test'
Requires-Dist: ipdb; extra == 'test'
Requires-Dist: pre-commit; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: ruff; extra == 'test'
Requires-Dist: ty; extra == 'test'
Description-Content-Type: text/markdown

# fruxon

[![PyPI version](https://img.shields.io/pypi/v/fruxon.svg)](https://pypi.org/project/fruxon/)
[![Python](https://img.shields.io/pypi/pyversions/fruxon.svg)](https://pypi.org/project/fruxon/)
[![License](https://img.shields.io/pypi/l/fruxon.svg)](https://github.com/fruxon-ai/fruxon-sdk/blob/develop/LICENSE)

Run, build, and orchestrate AI agents from your terminal — the official Python SDK and CLI for the [Fruxon](https://fruxon.com) platform.

## Install

```bash
pip install fruxon
```

Requires Python 3.10+.

## 30-second quickstart

```bash
fruxon login                 # opens a browser; stores the API key in your OS keychain
fruxon agents list           # see what's deployed in your org
fruxon run my-agent -p question="hello"
fruxon chat my-agent         # interactive multi-turn REPL
```

`fruxon doctor` will tell you if anything's misconfigured.

## The CLI

| Command | What it does |
| --- | --- |
| `fruxon login` | Browser-based sign-in. API key goes to your OS keychain (Keychain on macOS, Secret Service on Linux, Credential Manager on Windows). |
| `fruxon whoami` | Show the active key/org and where each value came from (flag, env, keychain, file). |
| `fruxon logout` | Forget stored credentials. |
| `fruxon agents list` | Browse every agent in your org. Use `--output json` for scripting, `--output id` for shell pipes. |
| `fruxon agents get <id>` | Inspect one agent — display name, deployed revision, tags, and the parameters it expects. |
| `fruxon agents test <id> --file <def.json>` | Run a draft flow definition against an existing agent without publishing it. Same output as `run`; exits non-zero on failure — a CI gate for agent changes. |
| `fruxon integrations list/get/create/update/verify` | Manage external integrations — the connections agents draw tools from. `create`/`update`/`verify` take a `--file` JSON body. |
| `fruxon tools list/get/create/update/delete/test` | Manage the tools inside an integration. Integration-scoped — every command takes `<integration>` as its first argument. `test` runs a tool with sample params before you wire it into an agent. |
| `fruxon run <agent>` | One-shot execution. Streams text by default; pass `--output json` or `--no-stream` for the full result envelope. |
| `fruxon chat <agent>` | Interactive REPL with session continuity. |
| `fruxon trace <agent> <record-id>` | Inspect a past execution — duration, cost, step-by-step trace. |
| `fruxon doctor` | Diagnose local setup (interpreter, SDK version, credentials, API reachability, auth). |
| `fruxon config` | Read/edit the persistent CLI config. |

### `fruxon run` — examples

```bash
fruxon run my-agent -p question="Hello" -p lang=en
fruxon run my-agent -p temp:=0.7 -p tags:='["a","b"]'   # ':=' for typed JSON
fruxon run my-agent -p prompt=@./prompt.md              # '@file' reads from disk
fruxon run my-agent --params ./params.json              # whole-object input
cat params.json | fruxon run my-agent --stdin
fruxon run my-agent --output json                       # full result envelope
fruxon run my-agent --revision 42                       # pin a specific revision
```

### Agent mode

When `CLAUDECODE=1`, `CI=1`, or `FRUXON_AGENT_MODE=1` is set, the CLI:
- defaults `--output` to `json` for `run`, `agents get`, `agents list`, `doctor`,
- suppresses banners and color chrome,
- emits a one-line JSON manifest on bare `fruxon` invocation describing auth state and next-step commands.

This makes the CLI ergonomic for LLM agents and CI pipelines without extra flags.

## The Python client

```python
from fruxon import FruxonClient

client = FruxonClient(api_key="...", org="acme-corp")

# One-shot
result = client.execute(
    "support-agent",
    parameters={"question": "How do I reset my password?"},
)
print(result.response)
print(f"{result.trace.duration}ms · ${result.trace.total_cost:.4f}")

# Multi-turn — thread the session ID into subsequent calls
followup = client.execute(
    "support-agent",
    parameters={"question": "Tell me more"},
    session_id=result.session_id,
)

# Streaming
for chunk in client.stream_text("support-agent", parameters={"question": "Hi"}):
    print(chunk, end="", flush=True)

# Lower-level: typed SSE events (text, tool_call, tool_result, done, …)
for event in client.stream("support-agent", parameters={"question": "Hi"}):
    ...

# Discovery
for agent in client.list_agents():
    print(agent.id, agent.current_revision)

params = client.get_agent_parameters("support-agent", revision=1)

# Test a draft flow without publishing it (same result shape as execute)
result = client.test("support-agent", {"flow": {...}, "baseRevision": 3, "parameters": {...}})
for event in client.stream_test("support-agent", {"flow": {...}}):
    ...

# Integrations & tools — the connections + capabilities agents are built from
for integ in client.list_integrations(types=["CUSTOM"]):
    print(integ.id, integ.type)
client.create_integration({"id": "github", "displayName": "GitHub", "configMetadata": {...}})
for tool in client.list_tools("github"):
    print(tool.id, tool.tool_type)
client.create_tool("github", {"id": "list_commits", "integrationId": "github", "descriptor": {...}})
client.test_tool("github", {"descriptor": {...}, "parameters": {"repo": "fruxon-sdk"}})
```

The client picks up `FRUXON_API_KEY`, `FRUXON_ORG`, and `FRUXON_BASE_URL` only if you read them yourself — the constructor takes explicit values. The CLI resolves them automatically (flags → env → stored config).

## Credentials & storage

The CLI resolves auth in this order (first non-empty wins):

1. Explicit flags — `--api-key` / `--org` / `--base-url`
2. Environment — `FRUXON_API_KEY` / `FRUXON_ORG` / `FRUXON_BASE_URL`
3. Stored credentials (managed by `fruxon login`)

The stored layer is split:

- **API key** → OS keychain via [`keyring`](https://pypi.org/project/keyring/). Set `FRUXON_NO_KEYRING=1` or let the keyring be unavailable to fall back to a `0600` JSON file.
- **Non-secrets** (`org`, `base_url`) → plain JSON under `~/.fruxon/credentials`.

`fruxon config list` shows both sources side by side.

## Environment variables

| Var | Effect |
| --- | --- |
| `FRUXON_API_KEY` | Default API key. |
| `FRUXON_ORG` | Default organization. |
| `FRUXON_BASE_URL` | Override the API base URL (staging / self-hosted). |
| `FRUXON_CONFIG_DIR` | Override the credentials directory (default `~/.fruxon`). |
| `FRUXON_DASHBOARD_URL` | Override where `fruxon login` points the browser. |
| `FRUXON_AGENT_MODE=1` | Optimize for AI-agent / script consumption (also auto-detected from `CLAUDECODE=1` / `CI=1`). |
| `FRUXON_NO_KEYRING=1` | Force the JSON-file fallback for the API key. |
| `FRUXON_NO_BANNER=1` | Suppress all branding chrome. |
| `FRUXON_NO_UPDATE_CHECK=1` | Opt out of the "newer version available" notifier. |
| `NO_COLOR=1` | Standard convention — disables color output. |

## Docs

- [Installation](docs/installation.md)
- [CLI reference](docs/cli.md)
- [Python client](docs/python-client.md)
- [Auth & configuration](docs/auth-and-config.md)

## License

MIT — see [LICENSE](LICENSE).
