Metadata-Version: 2.4
Name: fruxon
Version: 0.5.5
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 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 export` | Bundle a multi-file Python agent into a single file for import into Fruxon. |
| `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)
```

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).

## `fruxon export` — bundle a multi-file agent

```bash
fruxon export --copy                    # auto-detect entry point, copy to clipboard
fruxon export                           # auto-detect, print to stdout
fruxon export -o export.py              # write to file
fruxon export graph.py --copy           # explicit entry point
```

Works with LangChain, LangGraph, CrewAI, Google ADK, AutoGen, and any other Python agent framework. Scans for framework imports to find the entry point, traces local imports through Python's AST, and emits a single consolidated file (third-party packages stay external).

## 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).
