parallax-sdk 0.4.0

Official Python SDK for Parallax AI

Parallax AI — Python SDK

The official Python SDK for the Parallax AI platform. Covers REST endpoints across Iris, chats, characters, payments, and more, plus typed constants for every Iris workflow node.

Install

pip install parallax-sdk

Requires Python 3.9+. The import package is parallax_ai:

from parallax_ai import ParallaxAI

Quick start

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.

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/ for one runnable script per new node.

Examples

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:

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/