BrainScript
Automate decisions. Script intelligence.
BrainScript is a modular AI scripting engine that lets developers define complex decision-making workflows in Python — combining rule-based logic, external data sources, and Gemini AI into pipelines that think, adapt, and execute autonomously.
The Story
Why this exists.
The Problem
Building intelligent automation usually means stitching together LLM calls, conditionals, API calls, and data transforms in spaghetti code. There is no clean abstraction for 'AI-powered decision pipelines' that is both powerful enough for real use cases and simple enough to reason about.
Why It Matters
As AI becomes operational infrastructure — scheduling, triage, routing, analysis — developers need a programming model that treats AI reasoning as a first-class primitive alongside conditionals and loops. BrainScript is that model.
The Solution
A Python-based pipeline engine with a React + TypeScript UI. Developers define nodes (AI, logic, data, action) and connect them into directed graphs. The engine executes the graph, handles retries, logs every decision, and exposes results via a REST API.
Product Features
What it does.
AI Decision Nodes
Wrap any Gemini API call as a pipeline node — with structured output schemas, retry logic, and fallback values. AI reasoning becomes a testable, observable unit.
Conditional Branching
Define if/else branches based on AI output, API responses, or computed values. Pipelines adapt to runtime data rather than following a fixed script.
Data Source Connectors
Built-in connectors for MongoDB, REST APIs, and file inputs. Any node can pull external data as part of its execution context.
Execution Tracing
Every pipeline run is logged — inputs, outputs, decisions, latencies, and errors at each node. Full observability into what the AI decided and why.
Visual Pipeline Builder
A React-based drag-and-drop interface for constructing and visualising pipelines — no Python required for non-technical users.
System Architecture
How every layer connects.
Technical Deep Dive
Under the hood.
Pipeline Execution Engine
The engine represents a pipeline as a directed acyclic graph (DAG). Nodes are executed in topological order. Each node receives the outputs of its predecessor nodes as context. The engine uses Python's asyncio for concurrent independent branches — nodes with no dependency on each other run in parallel, reducing total pipeline latency by up to 60% on complex graphs.
async def execute_pipeline(pipeline: Pipeline, inputs: dict) -> dict:
graph = build_dag(pipeline.nodes, pipeline.edges)
results = {**inputs}
for node_id in topological_sort(graph):
node = graph[node_id]
ctx = {k: results[k] for k in node.inputs if k in results}
results[node_id] = await node.execute(ctx)
return resultsStructured AI Output with Schema Validation
Every AI node defines a JSON Schema for its expected output. The Gemini call is prompted to return JSON matching the schema. The engine validates the response against the schema before passing it to the next node — if validation fails, the node retries up to 3 times with the validation error appended to the prompt. This makes AI outputs reliable enough to use as control flow inputs.
Engineering Decisions
Challenge → Decision → Result.
Performance & Scale
By the numbers.
Deployment & Infrastructure
Production setup.
Deployment
Python engine containerised with Docker, deployed on Render. React frontend on Vercel. MongoDB Atlas for pipeline and execution storage.
CI/CD
GitHub Actions — Python pytest on PR, React type check + lint, auto-deploy on green CI.
Monitoring
Render metrics for engine CPU/memory. MongoDB Atlas for slow query alerts. Custom execution trace logging per pipeline run.
Challenges & Failures
What broke — and how I fixed it.
What I Learned
Key takeaways.
- 01
DAG execution models are the right abstraction for AI pipelines — topological sort naturally handles dependencies.
- 02
JSON Schema validation with retry feedback is more reliable than prompt engineering alone for structured AI output.
- 03
Asyncio in Python is powerful but requires careful exception handling — unhandled async exceptions silently kill tasks.
Future Roadmap
Where this is going.
v2.0 — 2026
- —Pipeline marketplace — share and fork community pipelines
- —Scheduled pipeline execution with cron triggers
- —Multi-model support — GPT-4o, Claude, Gemini switchable per node
Screenshots
The product.
Visual pipeline builder — nodes and connections
Pipeline execution trace — inputs, outputs, latencies
Technology Stack
Built with.
Engine
API
Frontend
AI
Database
Infrastructure
Deployment
Ready to dive in?