Metadata-Version: 2.4
Name: parallax-sdk
Version: 0.4.0
Summary: Official Python SDK for Parallax AI
Project-URL: Homepage, https://parallax-ai.app
Project-URL: Documentation, https://parallax-ai.app/docs/sdk
Project-URL: Repository, https://github.com/parallax-ai-llc/parallax-ai
Author-email: Parallax AI <dev@parallax-ai.app>
License-Expression: MIT
Keywords: ai,api,parallax,sdk
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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.25.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# Parallax AI — Python SDK

The official Python SDK for the [Parallax AI](https://parallax-ai.app) platform.
Covers REST endpoints across Iris, chats, characters, payments, and more, plus
typed constants for every Iris workflow node.

## Install

```bash
pip install parallax-sdk
```

Requires Python 3.9+. The import package is `parallax_ai`:

```python
from parallax_ai import ParallaxAI
```

## Quick start

```python
from parallax_ai import ParallaxAI

async def main():
    async with ParallaxAI(api_key="pk_...") as client:
        me = await client.users.me()
        print(me)

import asyncio; asyncio.run(main())
```

A synchronous client is also exported as `ParallaxAISync`.

## Iris workflow nodes

Node type identifiers, port shapes, and config-field metadata are auto-generated
from `packages/iris-nodes/dist/snapshot.json` and exposed through
`parallax_ai.iris_nodes`.

```python
from parallax_ai.iris_nodes import NodeType, get_node_definition

# All node types as string constants:
NodeType.GEN_TEXT_TO_TEXT            # 'GEN_TEXT_TO_TEXT'
NodeType.UTIL_ROUTER                 # 'UTIL_ROUTER'
NodeType.WEB_SEARCH                  # 'WEB_SEARCH'

# Full definition, including ports and config fields:
defn = get_node_definition(NodeType.UTIL_REGEX)
print(defn.label, defn.category)        # "Regex" "UTILITY"
print([p.name for p in defn.outputs])   # ['matches', 'firstMatch', 'replaced']
print([f.name for f in defn.config_fields])
```

`NodeDefinition` carries `can_be_tool` (whether the node is allowed in
`GEN_TEXT_TO_TEXT.mode='agent'` tool pickers) and each `NodeConfigField`
carries `depends_on` — a UI visibility hint of the form
`{"field": "<other-name>", "value": <expected-value>}` you can use for
conditional SDK-side validation.

### Phase 1 — newly added nodes

| Type | Category | Purpose |
|---|---|---|
| `WEB_SEARCH` | WEB | Perplexity Sonar search with 60-min cache. `canBeTool=True`. |
| `UTIL_ROUTER` | UTILITY | N-way conditional routing; first matching condition wins. |
| `UTIL_FILTER` | UTILITY | Pass-through gate based on a JS expression. |
| `UTIL_AGGREGATE` | UTILITY | Collect loop iterations into array / object / concatenated text. |
| `UTIL_TRY_CATCH` | UTILITY | Retry upstream with exponential backoff; route failures to `error`. |
| `UTIL_SUB_WORKFLOW` | UTILITY | Invoke another saved workflow as one step. |
| `UTIL_REGEX` | UTILITY | match / extract / replace with regular expressions. `canBeTool=True`. |
| `UTIL_DATE` | UTILITY | parse / format / add / diff with timezone support. `canBeTool=True`. |
| `UTIL_JSON_PATH` | UTILITY | Extract values via dot-bracket or JSONPath. `canBeTool=True`. |

`GEN_TEXT_TO_TEXT` also gained an `agent` mode that takes a `tools` array of
node IDs (each must be `canBeTool=True`) and a `maxIterations` safety cap.

### Phase 2 — RAG alternatives + structured AI + WEB scraping

| Type | Category | Purpose |
|---|---|---|
| `DOC_LONG_CONTEXT` | ANALYZER | Document Q&A via Claude 1M / Gemini 2M with prompt cache (90%+ repeat-query cost reduction). RAG alternative. `canBeTool=True`. |
| `DOC_GREP` | UTILITY | Literal/regex search inside a file with context lines. Zero LLM calls. `canBeTool=True`. |
| `AI_STRUCTURED_EXTRACT` | ANALYZER | Pull a typed object out of unstructured input via JSON Schema (OpenAI / Anthropic / Gemini). `canBeTool=True`. |
| `AI_CATEGORIZE` | ANALYZER | Single- or multi-label classification against a predefined label set. `canBeTool=True`. |
| `WEB_SCRAPER` | WEB | URL → clean markdown via Firecrawl / Jina Reader / Readability. `canBeTool=True`. |
| `WEB_YOUTUBE_TRANSCRIPT` | WEB | YouTube URL → transcript with timestamps; falls back to Whisper when no official captions. `canBeTool=True`. |

### Phase 3 — entry points + media + integrations

| Type | Category | Purpose |
|---|---|---|
| `TRIGGER_CHAT` | TRIGGER | Chat UI entry point with multi-turn `history` output and per-session `sessionId`. |
| `TRIGGER_FORM` | TRIGGER | Hosted form (dynamic field definitions) submits straight into the workflow. |
| `TRIGGER_EMAIL_RECEIVED` | TRIGGER | Start on inbound email (Gmail Pub/Sub push or IMAP polling) with subject/from filters. |
| `EDIT_AUDIO_SEPARATE` | EDITOR | Demucs/Spleeter stem separation: `vocals`, `instrumental`, `drums`, `bass`. |
| `EDIT_VIDEO_MERGE` | EDITOR | Concat up to 5 clips with fade/crossfade/cut transitions; LUFS audio normalization. |
| `EDIT_VIDEO_OVERLAY` | EDITOR | Composite text or image onto video (9-grid position, opacity/scale sliders, time range). |
| `GEN_LIP_SYNC` | GENERATOR | Re-sync mouth in a video to a different audio track (dubbing pipelines). |
| `OUTPUT_SLACK_POST` | OUTPUT | Block Kit / threaded messages to channels or users. |
| `OUTPUT_SHEET_APPEND` | OUTPUT | Append rows to Google Sheets with `columnMapping` + automatic header row. |

See [examples/](examples) for one runnable script per new node.

## Examples

```bash
git clone https://github.com/parallax-ai-llc/parallax-ai
cd parallax-ai/sdk-py
pip install -e .
python examples/agent_with_tools.py     # prints workflow JSON
```

Uncomment the `client.iris.create_workflow(**wf)` line in any example to
actually POST it to the API.

## Regenerating node constants

The maintainer flow when iris-nodes adds or changes a node:

```bash
pnpm --filter iris-nodes build           # writes dist/snapshot.json
cd sdk-py && python scripts/generate_iris_nodes.py
# → src/parallax_ai/iris_nodes.py is rewritten; commit the diff.
```

`generate_iris_nodes.py` is idempotent — running it without a snapshot change
produces zero diff.

## Links

- Homepage — https://parallax-ai.app
- SDK docs — https://parallax-ai.app/docs/sdk
- Node catalog — [`packages/iris-nodes/src/nodes/`](../packages/iris-nodes/src/nodes)
