GitHub - NomanRafique01/Zyron: 📱The first multi-agent AI platform for Android — specialist agents collaborate in parallel to analyze, execute, validate, and synthesize every response

                             ███████╗██╗   ██╗██████╗  ██████╗ ███╗   ██╗
                             ╚══███╔╝╚██╗ ██╔╝██╔══██╗██╔═══██╗████╗  ██║
                               ███╔╝  ╚████╔╝ ██████╔╝██║   ██║██╔██╗ ██║
                              ███╔╝    ╚██╔╝  ██╔══██╗██║   ██║██║╚██╗██║
                             ███████╗   ██║   ██║  ██║╚██████╔╝██║ ╚████║
                             ╚══════╝   ╚═╝   ╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═══╝

A multi-agent AI assistant for Android — built on a swarm of specialist models
that analyze, execute, and synthesize in parallel.

⚡ See It In Action

Agent Coordination	Live Talk Mode of Zyron

6 Teams
_{Domain-specialist squads for every query type}

24 Agents
_{Individual experts, each with a strict constitutional directive}

8 Providers
_{OpenAI · Anthropic · Gemini · Groq · Mistral · DeepSeek · GLM · OpenRouter}

1 Answer
_{All specialist outputs fused into one high-quality synthesized response}

One question. Four agents. Zero compromise.

📋 Table of Contents

What is Zyron?
🚀 What Makes Zyron Different
⚡ See It In Action
Screenshots
🎨 Agent Library
Core Architecture
Backend + Local Fallback Logic
All 6 Teams — All 24 Agents
Technologies Used
Feature Overview
Supported AI Providers
Tech Stack
Project Structure
Getting Started
Configuration
Agent Personas
Android Permissions
Security
Built with OpenAI Codex
License
Author

What is Zyron?

Zyron is a production-grade Android AI assistant that replaces a single chatbot with a coordinated swarm of four specialist agents running in parallel. Every query is routed to a team of domain experts — an analyst, an executor, a validator, and a synthesizer — whose outputs are fused into a single, high-quality response.

Unlike standard AI apps where one model does everything, Zyron assigns each agent a strict role and a constitutional directive. They compete, cross-examine each other's work, and only the synthesized result reaches the user.

🚀 What Makes Zyron Different

Feature	Zyron	Standard AI App
Parallel agents	✅ 3 specialists run simultaneously, not sequentially	❌ Single model, one pass
Team specialization	✅ 6 domain-tuned teams (code, science, finance, history, creative, general)	⚠️ One generalist model for everything
Local fallback	✅ Silent JS engine kicks in if cloud backend is unreachable	❌ App fails or shows error on network issues
Voice mode	✅ Full-duplex Live Talk with interrupt detection and sentence-level TTS	⚠️ Basic push-to-talk, no interrupt
On-device memory	✅ SQLite-backed conversation history + user memory facts injected into prompts	❌ No cross-session memory
BYOK security model	✅ Keys in Android Keystore, single read gateway, optional biometric lock	❌ Keys in plaintext or server-side only

Screenshots

_{Smart time-aware greeting — knows if you're a night owl or an early riser}	_{Watch four specialist agents race in parallel — every response built in real time}	_{Full-featured control center — configure every agent, key, and persona in one place}
_{Per-agent API wiring — swap models and providers independently without breaking the swarm}	_{Build your own specialist from scratch — name, traits, tone, and strength sliders, no code required}	_{Hands-free Live Talk — neural-net animation pulses live as Zyron listens, thinks, and speaks}

🎨 Agent Library

Core Architecture

                     User Query
                         │
                         ▼
┌┬─────────────────────────────────────────────────┬┐
││             Query Analyzer                      ││
││ Classifies: type · complexity · coordination    ││
││ Routes to: team blend or active team pipeline   ││
└┴───────────────────────┬─────────────────────────┴┘
                         │
     ┌───────────────────┼─────────────────────┐
     │                   │                     │
     ▼                   ▼                     ▼
┌─────────┐         ┌─────────┐           ┌──────────┐
│ Agent 1 │         │ Agent 2 │           │ Agent 3  │
│         │         │         │           │          │
│(Analyst │         │(Executor│           │(Validator│
│  /ADR)  │         │  /Impl) │           │ /QA/Red) │
└────┬────┘         └────┬────┘           └────┬─────┘
     │                   │                     │
     └───────────────────┼─────────────────────┘
                         │
               ┌┬────────┴─────────┬┐
               ││Specialist outputs││
               └┴────────┬─────────┴┘
                         │
                   ┌─────┴──────┐
                   │  Agent 4   │
                   │   Writer   │
                   │(Synthesizer│
                   │  /Output)  │
                   └─────┬──────┘
                         │
                         ▼
                  Final Response

The pipeline runs three phases:

Analysis — queryAnalyzer.js classifies intent, detects coding/STEM/creative signals, and selects COMPACT vs. FULL coordination mode
Specialist execution — Agents 1–3 run in parallel with individual SSE streaming, circuit-breakers, and automatic fallback chains
Synthesis — Agent 4 (Writer) receives a structured brief from Agents 1–3 and produces the final fused response, filtered by a quality judge and semantic deduplication

Backend + Local Fallback Logic

Zyron uses a dual-engine architecture — a Railway-hosted Python FastAPI backend as the primary orchestrator, with a fully self-contained local JS engine as a silent fallback. The user never sees the switch happen.

┌─────────────────────────────────────────────────────────┐
│                   backendBridge.js                      │
│                                                         │
│  1. POST /orchestrate → Railway backend (30 s timeout)  │
│         │                                               │
│         ├── ✅ 200 OK  → remap agents to active team   │
│         │              → return fused response          │
│         │                                               │
│         └── ❌ Timeout │ Network error │ Non-200        │
│                        │                                │
│                        ▼                                │
│         Local runAgentsOrchestrator() — silent fallback │
│         Full SSE streaming, circuit-breakers, dedup     │
└─────────────────────────────────────────────────────────┘

What the backend does

Python FastAPI on Railway (https://zyron-production-7af1.up.railway.app)
POST /orchestrate — accepts { query, agentConfigs, team, persona, userProfile, searchResults, documentContext }
Runs three specialist agents in parallel via LangGraph then synthesizes via the writer agent
Returns structured { text, agents[], tokenUsage, meta } JSON
POST /extract-document — accepts a base64-encoded file (PDF, DOCX, TXT) and returns extracted plain text for prompt injection
Web search — web_search.py fires a Tavily → Serper fallback search before the pipeline executes; key_facts from raw results (up to 5) are injected into every specialist prompt; returns None silently when both providers fail

Fallback guarantee

Timeout is 30 seconds. If the backend doesn't respond in time, the local engine starts immediately — no error is ever shown to the user
If the user pressed Stop while waiting, the abort propagates cleanly across both paths
Progress bar animation starts on the frontend while the backend call is in-flight: agents animate from 0 % → 78 % (exponential approach, τ = 28 s), then jump to 100 % on response
Agent names, icons, and accent colors are always remapped to the active team after a backend response — the backend drives logic, the frontend owns visual identity

All 6 Teams — All 24 Agents

Every team has 4 agents (Roles: Analyst · Executor · Validator · Synthesizer) with individual PNG icons, distinct accent colors, and specialist directives.

Team	Specialty	Best For
🧠 Mega Minds (Default)	Deep research & knowledge synthesis	Complex questions, concepts, analysis, and learning
💻 Coders	Software engineering & debugging	Features, refactors, algorithms, and code review
💡 Creative Thinkers	Creative strategy & original writing	Copywriting, storytelling, campaigns, and content
🔬 Scientists	STEM calculations & scientific reasoning	Physics, chemistry, mathematics, statistics, engineering
📜 Historians	Historical analysis & geopolitical context	Events, eras, biographies, and historical narrative
📈 Financers	Financial analysis & investment insight	Personal finance, corporate strategy, auditing

🧠 Mega Minds (Default Team)

Deep, clear answers to complex questions

Thoughtful knowledge and research team for concepts, analysis, and learning.

Agent 1 — Scholar	Agent 2 — Analyst	Agent 3 — Synthesizer	Agent 4 — Editor
Scholar	Analyst	Synthesizer	Editor
First-principles derivation, honest confidence levels (established vs. debated), counterarguments, hidden assumptions	Evidence strength, causal mechanism chains (A→B→C), comparative analysis, trade-off matrices	Bridging analogies, confusion-point bridges, mental models, core insight crystallized in one sentence	Builds definition → mechanism → nuance → analogy → insight; closes with perspective shift

💻 Coders

Clear, complete software construction

Practical coding team for features, refactors, algorithms, and debugging.

Agent 1 — Designer	Agent 2 — Programmer	Agent 3 — Debugger	Agent 4 — Executor
Designer	Programmer	Debugger	Executor
System structure, design decisions with plain-English rationale, API surface definitions, data flow	Complete working code — no placeholders, no TODOs, typed, error-handled, production-ready	Spots bugs, null dereferences, edge cases, security issues, performance traps — gives concrete fixes	Developer reference: Design → Code → Known Issues → Usage examples

💡 Creative Thinkers

Creative strategy and original writing

Creative team that thinks before it writes — strategy, drafting, editing, delivery.

Agent 1 — Strategist	Agent 2 — Creator	Agent 3 — Curator	Agent 4 — Narrator
Strategist	Creator	Curator	Narrator
Audience definition, creative angle, tone direction, traps to avoid, 2–3 genuinely different creative directions	Multiple opening options, a full complete draft, and a bold alternative version — real writing, no placeholders	Weakest lines diagnosed and rewritten, word choices sharpened, emotional arc mapped, what to cut	Final polished piece — best opening chosen, all editorial notes applied, crafted and intentional

🔬 Scientists

Clear scientific explanations and calculations

Practical STEM team for physics, chemistry, mathematics, statistics, and engineering.

Agent 1 — Theorist	Agent 2 — Experimenter	Agent 3 — Modeler	Agent 4 — Reporter
Theorist	Experimenter	Modeler	Reporter
Key equations with every symbol defined, step-by-step derivation in LaTeX, validity limits	Step-by-step calculation with units tracked, intermediate checkpoints, boxed final answer	Physical mechanism in plain language, everyday analogies with limits stated, real-world scale anchors	Lab-report structure: Theory → Calculation → Intuition → Result; all LaTeX preserved verbatim

📜 Historians

Clear, engaging historical answers

Knowledgeable history team for events, eras, biographies, and geopolitical context.

Agent 1 — Archivist	Agent 2 — Contextualist	Agent 3 — Cartographer	Agent 4 — Biographer
Archivist	Contextualist	Cartographer	Biographer
Verified chronologies, key actors and roles, epistemic status (Established / Probable / Contested / Unknown), source gaps	Trigger → intermediate → root cause chain, agency vs. structure, counterfactual reasoning	Timeline tables, comparison grids, geographic and demographic context, narrative structure blueprint	Authoritative scholarly narrative — honest about uncertainty, contextual judgment, no anachronism

📈 Financers

Expert financial insight across every domain

Master finance team for personal, corporate, and business finance.

Agent 1 — Accountant	Agent 2 — Adviser	Agent 3 — Auditor	Agent 4 — Investor
Accountant	Adviser	Auditor	Investor
Breaks down numbers, identifies patterns & trends, evaluates financial risk with data-driven reasoning	Strategic financial advice, investment guidance, tailored action plans, opportunity identification	Reviews for errors, compliance issues, red flags, control weaknesses, and inconsistencies	Structured financial report: Analysis → Advice → Audit Findings → Final Recommendation

Technologies Used

A full-stack overview of every layer Zyron is built on — from the on-device UI to the cloud orchestration backend.

Backend — Python / FastAPI / LangGraph

Technology	Version	Integration
Python	3.11	Backend runtime on Railway
FastAPI	0.111	REST API server — `/health` + `/orchestrate` endpoints
LangGraph	latest	Multi-agent pipeline graph — three parallel specialist nodes + writer synthesis node
LangChain	latest	LLM abstraction layer used inside LangGraph nodes for prompt building and provider calls
Pydantic	v2	Request / response model validation (`models.py`)
Docker	—	Containerised backend — consistent builds and local dev environment
Railway	—	Cloud deployment platform — auto-deploy from `main` branch
Uvicorn	—	ASGI server for FastAPI

Frontend — React Native / Expo

Technology	Version	Integration
React Native	0.81.5	Core UI framework — all screens, navigation, animations
Expo SDK	54	Build toolchain, native module access, OTA updates
expo-secure-store	—	Android Keystore-backed encrypted API key storage
expo-sqlite	—	On-device SQLite database for conversation + memory persistence
expo-speech	—	Text-to-speech output for Live Talk voice responses
expo-speech-recognition	—	Real-time STT — mic dictation and Live Talk input
expo-local-authentication	—	Biometric / PIN gate for API Config Lock
expo-blur	—	Settings modal blur backgrounds
expo-linear-gradient	—	Agent glow accent effects
expo-clipboard	—	Copy-to-clipboard on code blocks
expo-web-browser	—	GitHub OAuth redirect handler
react-native-webview	—	KaTeX LaTeX rendering sandbox
react-native-svg	—	SVG team icons, decorative elements, Live Talk neural animation
react-native-keyboard-controller	—	Cross-platform keyboard layout tracking
react-native-safe-area-context	—	Edge-to-edge safe area insets
@react-native-async-storage	—	User profile, team selection, custom agents + teams
@react-native-community/netinfo	—	Offline detection

AI Providers

Provider	Models Used	Role
OpenRouter	`nvidia/nemotron-3-super-120b-a12b:free` + 100+	Default free-tier agent socket
OpenAI	`gpt-4o-mini`, `gpt-4o`, o-series	General reasoning and synthesis
Anthropic	`claude-3-5-haiku-latest`, `claude-3-5-sonnet`	High-quality analysis and writing
Google Gemini	`gemini-2.5-flash`, `gemini-pro`	STEM, multimodal
Groq	`llama-3.3-70b-versatile`	Ultra-low-latency inference for Live Talk
Mistral	`mistral-small-latest`	Writer / synthesis agent default
DeepSeek	`deepseek-chat`, `deepseek-reasoner`	Extended chain-of-thought reasoning
GLM / Zhipu	`glm-4-flash`, `glm-4-air`	Low-cost high-speed inference

Data & Storage

Technology	Integration
SQLite (`expo-sqlite`)	Full conversation history, session index, user memory facts — all stored on-device
AsyncStorage	Non-sensitive user preferences — active team, profile settings, custom agents, custom teams
Android Keystore (`EncryptedSharedPreferences`)	All API keys — hardware-backed encryption, never stored in JS bundle or AsyncStorage

Rendering & Math

Technology	Integration
KaTeX 0.17	LaTeX formula typesetting — inline ( $...$ ) and display (`$$...$$`) math rendered in a sandboxed WebView
react-native-webview	WebView host for KaTeX rendering
mathParser.utils.js	Custom parser that detects and splits LaTeX and chemical formulae out of raw LLM text before rendering
SyntaxCode component	Syntax-highlighted code blocks with language auto-detection and copy-to-clipboard

Feature Overview

⚡ Multi-Agent Swarm Engine

Parallel execution — Agents 1–3 fire simultaneously, not sequentially
Team Blending — cross-team specialist borrowing per query without changing the active session team (e.g. pull Mega Minds' Scholar into a Coders session)
Coordination modes — NONE (direct), COMPACT (brief sharing), FULL (structured specialist briefs with shared context)
Model tier routing — cheap vs. expensive model selection based on query complexity
Team switching suggestions — the router detects when a different team would produce better results

🎙️ Live Talk Mode (New)

Zyron can be talked to directly — no typing required. Live Talk opens a full-screen voice conversation interface powered by a neural-network node-web animation that pulses in sync with microphone activity.

Pipeline:

Mic Input (STT)  →  Transcript  →  LLM Call (Agent 1 config)  →  TTS Output
     ↑                                                                │
     └──────── Interrupt detection (new voice kills TTS) ────────────┘

Speech-to-text via expo-speech-recognition — real-time partial results, silence detection
Continuous mic — hardware never closes between turns (no click sound); a 1.5 s silence timer triggers the LLM call
Text-to-speech via expo-speech — response is spoken sentence-by-sentence as tokens arrive, minimising latency
Interrupt — if the user speaks while Zyron is talking, TTS stops immediately and the new input is processed
Auto-close — if no speech is detected for 20 s after Zyron finishes speaking, the session closes silently
All providers supported — uses Agent 1's configured key/model (OpenAI, Anthropic, Gemini, Groq, Mistral, DeepSeek, GLM, OpenRouter)
Conversation saved — each turn is written to the active chat session in the background
Visual phases: idle → listening → thinking → speaking → back to listening

🎤 Mic / Voice Input (New)

The input bar now includes a microphone button alongside the text field. Tap it to dictate your message instead of typing — the transcript populates the input bar, and you can edit it before sending.

Lazy-loads expo-speech-recognition with a try/catch guard — gracefully disabled in Expo Go or stripped builds where the native module is not linked
Requests RECORD_AUDIO permission on first use
Live partial results update the input field in real time as you speak
Tap the mic button again (or tap Stop) to end dictation early

📡 Real-Time Streaming

Server-Sent Events (SSE) for all supporting providers — tokens stream live to screen
Per-agent streaming state — each agent has its own progress bar and status label (Thinking / Building / Stress-testing / Documenting / etc.)
Graceful abort — stop mid-generation, cancels cleanly across all active sockets

🔍 Web Search (New)

Zyron enriches every query with live web results before the agent pipeline runs — no manual "search mode" toggle required.

Pipeline:

User query
     │
     ▼
Web Search (Tavily → Serper fallback, 3 s timeout)
     │  key_facts[] + sources[]
     ▼
Injected into all specialist agent prompts
     │
     ▼
LangGraph multi-agent pipeline runs with grounded context

Dual-provider fallback — Tavily is the primary search provider; if it fails or is unconfigured, Serper is tried automatically
Silent degradation — if both providers return nothing, agents proceed using their own knowledge without any error shown
Grounded facts — up to 5 distilled key_facts extracted from raw search content (Tavily's auto-answer is intentionally ignored for accuracy) are injected into every specialist prompt
Source attribution — title, url, and snippet for each result are available alongside the facts
Session-level caching — duplicate queries within the same session reuse the cached result; cache is cleared on new chat
3-second hard timeout per provider — web search never blocks the pipeline for more than ~6 s total
Both engines supported — runs on the Railway backend (web_search.py) and on the local JS fallback engine (src/agents/search/)

🛡️ Resilient API Layer

Circuit breaker — per-provider failure tracking; tripped circuits skip that socket for the current session
Fallback chains — automatic failover to the next provider on timeout or error
Sanitized error messages — no raw API keys or stack traces ever surface in the UI

🔧 Agents Workshop (New)

Create fully custom agent personas and custom teams — no coding required.

Custom Agents (free):

Give the agent a name, description, and pick an icon from the 24-icon library (all built-in agent portraits available)
Configure personality traits (Critical Thinker, Systems Architect, Researcher, Innovator, Strategist, Mentor)
Set tone (Professional, Technical, Friendly, Formal, Direct, Creative) and communication style (Concise, Detailed, Structured, Educational, Executive)
Tune five strength sliders: Reasoning, Creativity, Analytical, Coding, Teaching (0–100)
metadataGenerator.js auto-generates contributionLens and specialistDirective from the form
Agents are stored in AsyncStorage and available immediately across all sessions
Edit, duplicate, or delete any saved custom agent

Custom Teams (premium):

Fill all four role slots (Agent 1–4) with agents from the custom agent library
Choose a team name, tagline, description, and one of 8 SVG team icons (Shield, Network, Atom, Lightning, Compass, DNA, Brain, Rocket)
Saved teams are merged with built-in teams at runtime via customTeamRegistry.js — they behave identically to built-in teams: full orchestration, streaming, synthesis, and team routing work with no changes

Registry merge logic (customTeamRegistry.js):

getAllTeams() → [...BUILTIN_TEAMS, ...customTeams]

Custom teams are bootstrapped async at app start then cached. All existing consumers (Agent Library, team router, runtime) call getAllTeams() with no conditional logic.

💾 On-Device Memory

SQLite persistence — full conversation history with session index and message pagination
User memory — contextual facts extracted from conversations and injected into future prompts

🔒 Security

Android Keystore-backed storage — API keys stored in EncryptedSharedPreferences via expo-secure-store; never in AsyncStorage or any JS bundle string
Single read gateway — keyGuard.js is the only permitted key-read path; keys are read at call-time and never stored in module-level variables
Optional API Config Lock — a password gate that locks all API settings behind biometric or PIN authentication
No telemetry — all telemetry is session-local, never transmitted

🧠 Synthesis Intelligence

Quality judge — LLM + heuristic scorer evaluates output against domain-specific required/prohibited criteria (coding, STEM, analytical, writing, creative, general)
Semantic deduplication — removes redundant content across agent outputs before synthesis
Agent personas — five Writer synthesis modes: Balanced, Creative, Precise, Educator, Executive

📐 Math & Code Rendering

LaTeX rendering — KaTeX via WebView for inline and display math formulas
Syntax-highlighted code blocks — dedicated SyntaxCode component with language detection and copy-to-clipboard
Chemical formula detection — mathParser.utils.js handles inline chemical notation alongside LaTeX

💬 Conversation Management

Timeline grouping — conversations bucketed into Today / Yesterday / Older
Session sidebar — slide-out drawer with conversation history, search, and new-chat creation
Smart welcome greeting — time-aware greeting (Night Owl / Early Bird / Golden Hour / etc.) with the user's first name

📎 Document Processing & Image Analysis (New)

Zyron can read and reason over documents and images — attach a file or image alongside your query and the agent swarm will analyze the content directly.

Document Processing:

PDF parsing — extract and analyze text content from PDF documents; the full extracted text is passed as context to the active agent team
Plain-text files — .txt, .md, .csv, .json, .xml and other text-based formats are read directly into the prompt context
Code files — source files (.js, .py, .ts, .jsx, .tsx, etc.) are passed to the Coders team with syntax-aware handling
Chunked context — large documents are chunked intelligently to fit within model context windows; key excerpts are surface-ranked before injection
Multi-document sessions — attach multiple documents in a single session; the agent team cross-references them in synthesis

Image Analysis:

Multimodal vision input — images are passed directly to vision-capable models (GPT-4o, Gemini 2.5 Flash, Claude 3.5 Sonnet) for analysis
Supported formats — PNG, JPG, JPEG, WEBP, GIF (static)
Use cases — diagram explanation, chart reading, screenshot debugging, handwritten note transcription, UI/UX critique, scientific image interpretation
Auto provider routing — if the active agent's configured model does not support vision, Zyron automatically routes the image query to the best available vision-capable provider without user action
Image + text combined — mix a written query with an attached image; the agents analyze both together and synthesize a unified response

Supported pipeline:

User attaches file / image
         │
         ▼
  fileProcessor.js   ──── PDF → text extraction (pdf-parse)
  imageHandler.js    ──── Image → base64 encode → multimodal payload
         │
         ▼
  Injected into agent prompt context (alongside user query)
         │
         ▼
  Agent swarm runs normally — all streaming, circuit-breakers,
  synthesis, and quality judge apply as usual

⚙️ Settings & Personalization

Profile panel — display name, role, preferred tone, language, coding style, detail level
Agent Library — accordion panel showing all six teams with per-team agent roster and expand-to-inspect detail
Agents Workshop — custom agent and custom team builder (described above)
API Config panel — per-provider key entry, model selection, key status verification, share-key-across-agents toggle
Privacy panel — privacy mode, profile context injection toggle
Reset panel — wipe conversation history, clear API keys, full factory reset

Supported AI Providers

Zyron connects to eight AI providers. Each agent socket is independently configurable.

Provider	Default Model	Notes
OpenRouter	`nvidia/nemotron-3-super-120b-a12b:free`	Free-tier NVIDIA, Cohere, and 100+ models
OpenAI	`gpt-4o-mini`	GPT-4o, o-series reasoning models
Anthropic	`claude-3-5-haiku-latest`	Claude 3.5 Sonnet/Haiku
Mistral	`mistral-small-latest`	Writer agent default
Google Gemini	`gemini-2.5-flash`	Flash and Pro variants
DeepSeek	`deepseek-chat`	`deepseek-reasoner` for extended CoT
Groq	`llama-3.3-70b-versatile`	Ultra-low-latency inference
GLM / Zhipu	`glm-4-flash`	GLM-4 Flash, Air, Plus

All providers support free model tiers where available. Keys are stored per-agent and can be shared across agents via the share-key setting.

Tech Stack

React Native 0.81.5 + Expo SDK 54
├── expo-secure-store              Android Keystore-backed key storage
├── expo-sqlite                    On-device conversation + memory persistence
├── expo-speech                    TTS — Live Talk voice output
├── expo-speech-recognition        STT — Mic input + Live Talk voice input
├── expo-local-authentication      Biometric/PIN API lock gate
├── expo-blur                      Settings modal blur backgrounds
├── expo-linear-gradient           Agent glow effects
├── expo-clipboard                 Code block copy-to-clipboard
├── expo-web-browser               GitHub OAuth redirect handler
├── react-native-webview           KaTeX LaTeX rendering
├── react-native-svg               SVG icons, decorative elements, team icons
├── react-native-keyboard-controller  Cross-platform keyboard layout tracking
├── react-native-safe-area-context    Edge-to-edge safe area handling
├── @react-native-async-storage       User profile, team selection, custom teams/agents
├── @react-native-community/netinfo   Offline detection
└── katex 0.17                     LaTeX math typesetting

Backend: Python 3.11 · FastAPI · LangGraph · Railway deployment

Build toolchain: EAS Build with development / preview / production-APK / production-AAB profiles.

Project Structure

Zyron/
├── App.js                       React root — SplashScreen + MainApp
├── index.js                     Expo entry point + global error handler
├── app.config.js                Active Expo config (merges .env secrets)
├── eas.json                     EAS Build profiles
│
├── assets/
│   ├── agent-icons/             24 agent portrait PNGs (6 teams × 4 agents)
│   │   ├── financers/           accountant · adviser · auditor · investor
│   │   ├── coders/              designer · programmer · debugger · executor
│   │   ├── scientists/          theorist · experimenter · modeler · reporter
│   │   ├── mega-minds/          scholar · analyst · synthesizer · editor
│   │   ├── historians/          archivist · contextualist · cartographer · biographer
│   │   └── creative/            strategist · creator · curator · narrator
│   ├── icons/                   Favicon + web icons
│   ├── images/                  In-app logo assets
│   └── splash/                  Android adaptive icon + splash screen
│
├── backend/                     ◀ Python FastAPI backend (Railway)
│   ├── main.py                  FastAPI app — /health + /orchestrate + /extract-document endpoints
│   ├── models.py                Pydantic request/response models
│   ├── orchestrator.py          Backwards-compat shim → re-exports from orchestrator/ package
│   ├── orchestrator/            LangGraph pipeline package (_state, _utils, _nodes, _graph, _pipeline)
│   ├── web_search.py            Web search — Tavily → Serper fallback; injects key_facts into agent prompts
│   ├── document_extractor.py    Base64 file → plain text (PDF via pdfminer.six, DOCX via python-docx, TXT)
│   ├── query_analyzer.py        Query classification
│   ├── prompt_builder.py        Backwards-compat shim → prompt_builder/ package
│   ├── prompt_builder/          Prompt construction package (_specialist, _writer, _templates, _style, _user_profile)
│   ├── providers.py             Provider HTTP clients
│   └── requirements.txt
│
├── plugins/
│   └── withAndroidWindowBackground.js  Prevents white flash on cold launch
│
└── src/
    ├── agents/                  ◀ Core AI swarm engine
    │   ├── backendBridge.js         Primary entry point — backend first, local fallback
    │   ├── orchestrator.js          Local pipeline runner (fallback engine)
    │   ├── analysis/                Query classifier
    │   ├── api/                     Provider HTTP clients + circuit-breaker + fallback
    │   ├── memory/                  SQLite on-device memory store
    │   ├── offline/                 On-device offline inference fallback
    │   ├── progress/                Per-agent progress state tracker
    │   ├── prompts/                 Prompt builder + domain templates
    │   ├── registry/                Agent registry + team metadata + persona instructions
    │   ├── router/                  Team router + model tier selector
    │   ├── search/                  Web search — Tavily → Serper fallback (webSearch.js, searchProviders.js, searchResultFormatter.js)
    │   ├── security/                keyGuard — single key-read gateway
    │   ├── streaming/               SSE stream manager
    │   ├── synthesis/               Synthesizer + quality judge + semantic dedup
    │   ├── teams/                   6 built-in team definitions + teamRuntime + teamBlend
    │   ├── telemetry/               Session-local latency/token/error metrics
    │   ├── tools/                   Tool registry + sandboxed JS code executor
    │   └── workshop/                Custom agent/team storage + registry + metadata generator
    │
    ├── components/
    │   ├── agent/               AgentPanel, AgentBadge, AgentCoordinationTab, AgentIcon
    │   ├── chat/                ChatBubble, ChatMessageList, SyntaxCode, MarkdownText
    │   ├── input/               InputBar — mic button, Live Talk button, agent-strip dots
    │   ├── layout/              Header (glow/offline), SidebarDrawer
    │   ├── math/                MathFormula (KaTeX via WebView)
    │   ├── modals/              NeuralNetLiveTalk, ConfirmDialog, SetupGuideModal
    │   ├── shared/              Icons (SVG), PasswordField, WelcomeLogo
    │   └── workshop/            AgentBuilderPanel, TeamBuilderPanel, CustomAgentsLibrary
    │
    ├── config/
    │   ├── appConfig.js             Agent defaults, provider models, user profile schema
    │   ├── colors.config.js         Design token palette (agent accent colors, glows)
    │   ├── apiLock.config.js        SecureStore key constants for API lock
    │   ├── agentPersona.config.js   Writer synthesis persona options
    │   └── agentIconOptions.js      Centralised 24-icon asset catalogue (for custom agents)
    │
    ├── database/
    │   └── db.init.js               SQLite schema + all message CRUD operations
    │
    ├── hooks/
    │   ├── useAgentExecution.hook.js    Send/stop/regenerate, agent state updates
    │   ├── useAgentSockets.hook.js      Key load/save/verify, team selection, engine toggle
    │   ├── useConversations.hook.js     Session index, message pagination, new/delete chat
    │   ├── useLiveTalk.hook.js          Live Talk pipeline — STT → LLM → TTS + interrupt
    │   ├── useSettings.hook.js          Settings modal, password manager, API lock, profile
    │   └── useToast.hook.js             In-app toast: show/dismiss, swipe-to-dismiss
    │
    ├── screens/
    │   ├── chat/MainApp.screen.jsx      Composition root — wires all hooks and components
    │   ├── splash/SplashScreen.screen.jsx  Animated custom splash
    │   └── settings/
    │       ├── SettingsModal.screen.jsx
    │       ├── panels/                  Profile, AgentLibrary, AgentsWorkshop, ApiConfig, Privacy, About, Reset
    │       ├── auth/                    ApiLockGate, PasswordManager, RemoveLockBanner
    │       └── rows/                    AgentSocketRow
    │
    ├── styles/
    │   ├── app.styles.js            Master stylesheet
    │   └── *.styles.js              Layout, feedback, welcome, sidebar, settings, profile, socket, auth
    │
    └── utils/
        ├── agentLogic.utils.js          Backward-compatible facade for agents public API
        ├── mathParser.utils.js          LaTeX / chemical formula detection and splitting
        ├── responseGenerator.utils.js   Legacy direct API caller
        └── responsive.utils.js          Dimension-based scale/spacing/fontScale helpers

Getting Started

Prerequisites

Node.js 18+
Expo CLI (npm install -g expo-cli)
EAS CLI (npm install -g eas-cli) for builds
At least one API key from any supported provider

Installation

git clone https://github.com/NomanRafique01/zyron.git
cd zyron
npm install

Running in Development

# Start Metro bundler
npx expo start

# Run on connected Android device / emulator
npx expo run:android

Building a Release APK

# Preview APK (internal distribution)
eas build --profile preview --platform android

# Production APK
eas build --profile production-apk --platform android

# Production AAB (Play Store)
eas build --profile production --platform android

Configuration

API keys are entered directly in the app's Settings → API Config panel after launch. Keys are stored in Android Keystore-backed encrypted storage — never in source code or config files.

For .env-based secrets (used at build time only via app.config.js):

cp .env.example .env   # if provided
# or create manually — see app.config.js for expected variables

⚠️ Security note: This is a client-only app. See SECURITY.md for key storage architecture, spend-cap guidance for every provider, and the recommended Cloudflare Worker proxy for production deployments.

Agent Personas

The Writer agent (Agent 4) supports five synthesis personas, selectable in Settings:

Persona	Behavior
Balanced	Professional synthesis of all specialist outputs
Creative	Unconventional angles, vivid language, memorable framing
Precise	Strict correctness, concrete numbers, numbered steps, zero filler
Educator	Progressive concept building, analogies, Key Takeaway at close
Executive	Lead with conclusion, max 3 paragraphs, one-line Action/Decision

Android Permissions

Permission	Purpose
`INTERNET`	API calls to all AI providers
`VIBRATE`	Haptic feedback on send / toast
`RECORD_AUDIO`	Mic input dictation + Live Talk STT
`USE_BIOMETRIC`	Biometric gate for API Config Lock
`USE_FINGERPRINT`	Fingerprint unlock for API Config Lock

Minimum SDK: 21 (Android 5.0) Target SDK: 34 (Android 14)

Security

API keys live on the device. The app's security model is built around three principles:

Encrypted storage — Android Keystore-backed EncryptedSharedPreferences via expo-secure-store
Single read path — keyGuard.js is the only file that reads keys; no key is ever assigned to a module-level variable or logged
Spend caps — the most important protection is a hard monthly spend limit on every provider dashboard (see SECURITY.md)

For production deployments requiring keys to leave the device entirely, SECURITY.md describes a ~50-line stateless Cloudflare Worker / Vercel Edge Function proxy that eliminates on-device key storage.

Built with OpenAI Codex

OpenAI Codex · _{powered by GPT‑4o · o3 · GPT‑5.5}

OpenAI Codex was the AI coding assistant used throughout the entire development lifecycle of Zyron — from architecture decisions and backend design all the way to UI polish and documentation.

Area	What Codex handled
UI logic & planning	Component hierarchy, state-management patterns, hook extraction strategy, and overall screen flow
Dynamic & responsive UI	Animated coordination panels, adaptive layouts, keyboard-avoidance logic, and gesture-driven interactions
Feature implementation	`MainApp.screen.jsx`, agent pipeline screens, settings panels, and chat-flow components
Code review & refinement	Code quality passes, refactor suggestions, and pattern enforcement throughout iteration
Debugging	Race conditions in the agent pipeline, RAF-batching issues, animation driver conflicts, storage-migration edge cases
Architecture decisions	Agent-orchestration design, LangGraph pipeline structure, circuit-breaker fallback chains
Backend design	FastAPI / LangGraph orchestration layer, document-extraction endpoint, Railway deployment
Deployment	EAS build profiles, Play Store AAB configuration, Railway production, environment-variable strategy
Documentation	Writing and maintaining this README, `SECURITY.md`, `CHANGELOG.md`, `STRUCTURE.md`, and all in-code JSDoc
Git & version control	Commit message authoring, branch strategy, release tagging, and changelog generation

License

MIT — see LICENSE.md

Author

Noman Rafique nomanrafique.official01@gmail.com

Six specialist teams. Eight AI providers. One coherent answer.

Zyron — Think in swarms.

Name		Name	Last commit message	Last commit date
assets		assets
backend		backend
plugins		plugins
scripts		scripts
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
.npmrc		.npmrc
App.js		App.js
CHANGELOG.md		CHANGELOG.md
LICENSE.md		LICENSE.md
README.md		README.md
SECURITY.md		SECURITY.md
STRUCTURE.md		STRUCTURE.md
app.config.js		app.config.js
app.json		app.json
babel.config.js		babel.config.js
eas.json		eas.json
index.js		index.js
metro.config.js		metro.config.js
package-lock.json		package-lock.json
package.json		package.json

Latest commit

History

Folders and files

Repository files navigation