Elis AI

A dynamic AI orchestration platform that routes user prompts through adaptive agent chains, executes them across distributed model miners, and continuously improves routing quality through feedback-driven evaluation.

Current Listen Mode

• Listen currently uses browser-native speech by default.
• Server-side TTS via Piper is optional and only active when Piper and a voice model are installed in the backend container.

Architecture Overview

┌──────────┐     ┌──────────┐     ┌────────────────────────────────────┐
│ Frontend │────▶│ Backend  │────▶│           Orchestrator             │
│ (Next.js)│◀────│ (Flask)  │◀────│  Router → Agent Chain → Executor  │
└──────────┘     └──────────┘     └──────┬──────────┬────────────┬────┘
                                         │          │            │
                                    ┌────▼───┐ ┌───▼────┐  ┌───▼────┐
                                    │ Tools  │ │ Miners │  │  DB    │
                                    │ (70+)  │ │ (single)│ │(pgvec) │
                                    └────────┘ └────────┘  └────────┘

Two-Layer Chain System

• Router chains — select the best agent for a given prompt using similarity scoring, prior quality (EMA), and live miner feasibility.
• Agent chains — reusable execution blueprints containing rules, knowledge-base references, tool bundles, and multi-step workflow definitions.

Miner System

Model execution is dispatched to miners — containerized inference workers running OpenAI-compatible or Ollama-based models. Miners register over WebSocket and are scheduled by tier (nano / small / frontier / self-hosted).

Feedback & Evaluation

Every run produces a full trace (router selection, agent chain steps, tool calls, model I/O). A grading pipeline scores outputs and propagates EMA quality signals back to agents, templates, tool bundles, and model profiles — driving future routing decisions.

Project Structure

elis-ai/
├── backend/                 # Python backend service
│   ├── agents/              # Core orchestration engine
│   │   ├── orchestration.py #   Chain executor, skill chains, execution modes
│   │   ├── router.py        #   Dynamic router-chain selection & ranking
│   │   ├── db.py            #   PostgreSQL + pgvector data layer
│   │   ├── vectorstore.py   #   Embedding search (agents, templates, bundles)
│   │   ├── tools/           #   70+ tool implementations
│   │   │   ├── bundle_resolver.py    # Tool bundle resolution + universal tools
│   │   │   ├── tool_calling_service.py # LLM function-calling dispatch
│   │   │   ├── web_search_service.py   # Web search integration
│   │   │   ├── sql_agent_tool.py       # LangChain SQL agent
│   │   │   └── ...
│   │   ├── seeds/           #   Seed data & agent catalog
│   │   ├── templates/       #   Agent templates
│   │   └── ...
│   ├── api.py               # REST API (auth, conversations, messages)
│   ├── company_api.py       # Multi-tenant company endpoints
│   ├── miner_api.py         # Miner registration & management
│   ├── miner_ws.py          # Miner WebSocket handler
│   ├── server.py            # Flask app setup & CORS
│   ├── main.py              # Orchestration entry point
│   ├── auth.py              # JWT + bcrypt authentication
│   └── tests/               # Unit & integration tests
├── frontend/                # Next.js 14 React application
│   ├── app/                 #   App router (pages, layouts, API routes)
│   ├── components/          #   React components (chat, blocks, trace, admin)
│   ├── hooks/               #   Custom React hooks
│   ├── lib/                 #   Utility functions & API client
│   └── styles/              #   Tailwind CSS
├── miner/                   # Model inference workers
│   ├── app.py               #   Flask miner service
│   ├── Dockerfile           #   OpenAI-based miner
│   ├── Dockerfile.ollama    #   Ollama self-hosted miner
│   └── openai_miners.json   #   Model definitions
├── browser_service/         # Selenium browser automation
├── services/                # Shared services (KBS)
├── config/                  # Configuration files
├── docs/                    # Documentation
├── docker-compose.yml       # Full stack compose (all services)
└── docker-compose.miners.yml # Azure miner deployment config

Tech Stack

Prerequisites

• Docker and Docker Compose (v2+)
• Node.js 18+ (for local frontend development)
• Python 3.11+ (for local backend development)
• OpenAI API key (for OpenAI-based miners)

Quick Start

1. Clone and configure

git clone <repo-url> elis-ai
cd elis-ai

Copy and edit environment files for each service:

# Backend
cp backend/.env.example backend/.env    # Set DB, Redis, JWT secrets

# Miner
cp miner/.env.template miner/.env      # Set OPENAI_API_KEY, enrollment secret

# Frontend
cp frontend/.env.example frontend/.env  # Set NEXT_PUBLIC_API_URL

2. Start with Docker Compose

docker-compose up -d --build

This starts all services:

3. Access the application

• Web UI: http://localhost:3000
• API: http://localhost:8000
• PgAdmin: http://localhost:5050

Configuration

Key Environment Variables

Orchestration Flow

Each user message follows this execution pipeline:

RECEIVE → PRE_RESPONSE_GATE → GENERATE → DELIVER → PERSIST

1. Receive — Parse user message, resolve tenant context.
2. Pre-Response Gate — Evaluate context size, token budget, memory tiers.
3. Generate — Router selects agent chain → executor dispatches to miners with tool access.
4. Deliver — Stream response blocks (text, evidence, artifacts) to the frontend via SSE.
5. Persist — Store adaptive records, update embeddings, trigger template candidate generation.

Execution Modes

The orchestrator dynamically selects one of four modes per request:

• direct_answer — Simple factual responses.
• retrieval_augmented — Augmented with KB/document retrieval.
• skill_chain — Multi-step workflow (search → expertise → context → answer).
• multi_step_workflow — Complex task decomposition and execution.

Multi-Tenancy & Roles

The platform supports multi-tenant company isolation with role-based access:

Automations Product (Widgets)

• Automations is an organization-scoped product surface for recurring research widgets.
• The UI unlocks only when the user belongs to at least one organization.
• Widgets support mobile-friendly layout behavior, responsive controls, and drag/resize cards.
• Output modes include chart-first and non-chart render styles: bar, line, pie, doughnut, radar, table, and text.
• Notification dispatch supports threshold/text criteria plus a Test Alert Now action for immediate email verification.

Development

Backend (local)

cd backend
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\Activate.ps1 on Windows
pip install -r ../requirements.txt
python -m flask --app server:app run --port 8000

Frontend (local)

cd frontend
npm install
npm run dev

Running Tests

cd backend
python -m pytest tests/ -v

Deployment

The platform deploys to Azure Container Apps using Docker images pushed to GitLab Container Registry. See deploy.md for detailed deployment instructions.

# Build and push images
docker build -t [private container registry]/backend:v1.0.5 -f backend/Dockerfile .
docker build -t [private container registry]/frontend:v1.0.5 -f frontend/Dockerfile .

# Deploy via Azure CLI
az containerapp update --name backend --resource-group <rg> --image <backend-image>
az containerapp update --name frontend --resource-group <rg> --image <frontend-image>

License

Proprietary. All rights reserved.

Architecture & Performance Audit Report

Date: 2026-03-16
Baseline: 43.7s avg/turn (10-turn ML conversation), single-miner dispatch, 2 active OpenAI miners
Scope: Full backend orchestration pipeline — router → context → executor → persistence → tools

Part 1: Full Findings by Severity

CRITICAL

HIGH

MEDIUM

LOW / INFO

Part 2: Three-Frame Classification

Frame 1: Latency-Critical Hot Path (blocks user response)

These operations execute before the user sees any response:

Total hot-path LLM calls per request: 2-12 (1 mandatory executor + 1 mandatory tool planner + 0-10 conditional)

Frame 2: Can Be Deferred Until After Answer

These run synchronously but could be moved to background:

Frame 3: Can Run in Parallel Safely

These are currently sequential but have no data dependencies between them:

Part 3: Prioritized Action Plan

A. Top 10 Highest-Impact Fixes

B. Quick Wins (Under 1 Hour Each)

C. Refactors (Under 1 Day Each)

D. Larger Architectural Improvements

E. Benchmark Plan

Baseline Measurements Needed

Instrumentation Steps

1. Add structured timing to orchestration.py: Wrap each phase in perf_counter() pairs:
   - CONTEXT_LOAD, CONTEXT_PACK, NARROW_ROUTE, FACET_DECOMPOSE, EXPERT_SELECT, TOOL_PLAN, EXECUTOR, POSTPROCESS, PERSIST_ADAPTIVE
2. Count external API calls: Add counter in EmbeddingService.embed() and ModelGateway.generate() — log per-request totals.
3. Count DB queries: Add query counter in db.py cursor wrapper — log per-request total.

Test Protocol

A/B Comparison Framework

For each fix from the Top 10:
1. Run T1 (10-turn) as baseline
2. Apply fix
3. Run T1 again
4. Compare: Δ = (baseline_avg - fix_avg) / baseline_avg × 100%
5. Accept if: Δ > 5% AND no quality regression (all turns pass)

Part 4: Orchestration Pipeline Deep Dive

Request Lifecycle with LLM/DB/Embed Call Counts

HTTP POST /chat  →  main.py (6 phases)
│
├─ RECEIVE (0 LLM, 0 DB, 0 embed)
│  └─ Parse request, validate auth
│
├─ PRE_RESPONSE_GATE (0-1 LLM, 2-4 DB, 0-1 embed)
│  └─ recall_artifacts_for_prompt()  →  cosine classifier (no LLM)
│  └─ load_conversation_context()
│     ├─ _filter_run_log()           →  1 DB query, N×json.loads
│     ├─ _load_persistent_snapshot() →  1 DB query
│     ├─ _load_persistent_facts()    →  1 DB query
│     └─ _load_persistent_tasks()    →  1 DB query
│
├─ GENERATE  →  orchestration.py execute()
│  │
│  ├─ WorkingContextAssembler.build()  (0-5 LLM, 0 DB, 0 embed)
│  │  └─ ContextPacker.pack()
│  │     ├─ _rank_semantic_facts()     →  no LLM
│  │     ├─ _orch_transform() × 3-5   →  summarizer.summarize() IF text > limit
│  │     └─ _build_compacted_pack()    →  no LLM
│  │
│  ├─ Routing Decision
│  │  ├─ narrow_route()                →  0-1 LLM (default: 0)
│  │  ├─ FacetDecomposer.decompose()   →  0 LLM, 1 embed, 1-2 DB
│  │  └─ _find_best_expert() × facets  →  0 LLM, 2×F DB queries
│  │
│  ├─ Tool Planning (if tools needed)
│  │  └─ plan_tool_invocation()        →  1 LLM (mandatory)
│  │     └─ execute_tool() × planned   →  0 LLM (tools make own calls)
│  │
│  ├─ Primary Executor                 →  1 LLM (ModelGateway.generate)
│  │  └─ Cascade: miner_proxy → openai_direct → ollama (60s→120s timeouts)
│  │
│  ├─ Evaluation + Repair Loop (if output fails grade)
│  │  └─ Per retry: 1 LLM call         →  up to N retries
│  │
│  ├─ apply_postprocess_pipeline()     →  0 LLM (pure transforms)
│  │
│  └─ _persist_adaptive_after_run()    ← SYNCHRONOUS, BLOCKS RETURN
│     ├─ _llm_classify_domain()        →  1 LLM
│     ├─ persist_adaptive_records()
│     │  ├─ N step writes              →  N DB inserts
│     │  ├─ M artifact writes          →  M DB inserts
│     │  ├─ 2M artifact embeddings     →  2M embed API calls
│     │  ├─ 1 agent index embed        →  1 embed API call
│     │  ├─ 1 domain label embed       →  1 embed API call
│     │  └─ 1 chain variant embed      →  1 embed API call
│     └─ save_router_trace()           →  1 DB insert
│
├─ DELIVER (0 LLM, 1 DB, 0 embed)
│  └─ SSE stream to frontend
│
├─ PERSIST (0 LLM, 1-2 DB, 0-1 embed)
│  └─ embed_message() + save_message()
│
└─ READY

Per-Turn Cost Summary (typical case)

Highest-Value Cuts to This Pipeline

1. Background _persist_adaptive_after_run() → saves 1 LLM + N+M+8 DB + 3+2M embeds from blocking
2. Cache episode summaries → saves 0-5 LLM in _orch_transform()
3. Heuristic-first tool planning → saves 1 LLM on simple/repeat queries
4. Single-embed artifacts → saves M embed calls (deduplicate)
5. Parallel context queries → saves 3× DB round-trip wait

Conservative estimate applying fixes 1-5: 43.7s → 25-30s avg/turn (~30-43% improvement)

Appendix: File Index

[...content truncated for whitepaper synthesis...]

Task Orchestration Context Policy

Single source of truth for context packing, planning inputs, budget
allocation, and telemetry in the task-orchestrated execution path.

Implementation and tests should reference this document by path.

1. Purpose & Scope

This policy governs how the task-orchestrated pipeline builds, packs,
and observes inter-node context. It applies to:

• TaskExecutionService (DAG execution, input context building)
• DependencyContextPacker (multi-dep budget allocation)
• _build_planned_nodes / _expand_web_research_nodes_impl (graph planning)
• TaskCompilationService (merge and failure manifest)
• _task_tool_executor (tool bundle narrowing, structured data extraction)

It does not govern ChainExecutorService or non-task tool loops.

2. Consumer Classification

Every edge between task nodes has a next consumer type:

Default: llm unless next_consumer_type is set in PlannedTaskNode.metadata.

3. Summarize vs Chunk Decision Table

4. Planning Inputs

Allowed for task-graph building:

• _extract_rule_based in StructuredExtractor (regex, keyword lists)
• Orchestration-level regex/heuristics (compound prompt split, list detection)
• SummarizerService only to shorten long prompts before regex passes

Not allowed for planning: _extract_with_llm, _EXTRACTION_PROMPT,
or any LLM-based JSON extraction for minting graph nodes.

5. Budget & Metadata Schema

Additive keys on PlannedTaskNode.metadata (no dataclass change):

6. v1 Packing Algorithm

Single-shot after all dependencies complete (DependencyContextPacker.pack):

1. Measure size_raw(d) for each dep summary + structured_data.
2. Allocate proportional to dependency_context_weights (default equal).
3. Apply floors from dependency_context_floor_chars (default 200).
4. Fit: summarize for LLM, chunk for aggregator.
5. Trim order: ascending weight first, respect floors.

Reserve 20% of budget for structured_data keys (URLs, dates, evidence).

7. Failure / Partial Handling

• Scheduler default: run child nodes even when parent status = failed
  (_parallel_groups tracks completion, not success).
• Packer: insert [dep_id]: (failed) placeholder for failed deps.
  Redistribute freed budget to remaining active deps.
• Compile: produce failure_manifest list with {node_id, tool_name, error_class, message, retryable} for each failed node.

8. Settings Catalog

9. Telemetry Contract

build_task_telemetry emits per node:

• Standard: task_id, status, latency_ms, retry_count, error,
  quality_signals, output_confidence
• Planning: task_type, domain, planning_confidence, tool_hints,
  dependencies
• Metadata: web_task_role, web_task_index, url_rank, task_role,
  primary_tool, next_consumer_type
• Binding: expert/model/miner selection details

10. tool_hints ↔ _TOOL_HINTS_NEEDING_TOOLS Contract

_node_needs_tools uses exact-match membership in frozenset.

Current set:

web_search, search, web, browse, fetch,
micro_web_extract_content, micro_extract_chart_data,
web_search_discover, web_content_reader, direct_url_lookup,
sql_query, rest_api_query,
knowledge_base_search, hybrid_retrieval,
generate_chart

Rule: every new tool_hints value emitted by _build_planned_nodes
or the web expander must have a matching entry added to the frozenset
in the same change, or routing silently falls back to _task_model_executor.

11. Observability for Degraded Completion

When any node fails:
1. failure_manifest is produced at compile time.
2. Warnings list includes task_failed:{node_id}.
3. The failure manifest can be injected into the model prompt
for honest partial-answer generation.

12. Integration / Linked-Resource Context

• SQL/REST: only inject sql_query / rest_api_query hints when
  _prompt_requires_linked_sql_lookup / _prompt_requires_linked_rest_api_lookup
  returns True AND tenant has linked resources.
• Integrations (OAuth): only add OAuth tools when the org has active,
  configured connections. Fail-closed: omit tool + record diagnostic.
• Platform APIs: subject to tenant web policy
  (filter_tool_specs_for_web_policy).

13. Web Artifact Dates & Recency

• content_collected_at: ISO 8601 UTC, set at fetch/normalization time.
  Required for every web-sourced item.
• published_at: ISO 8601 UTC or null. Extraction order:
  HTML <meta article:published_time>, JSON-LD datePublished,
  OpenGraph, HTTP Last-Modified.
• Packer treats date fields as non-droppable structured keys.

Memory Tier Model

Overview

All conversation memory is organised into five tiers, ranked by context
priority. The guiding principle is:

Raw data is canonical and never replaced by summaries. Summaries are
derived artifacts only. Performance work must not convert authoritative
memory into compressed heuristics.

The 5 Tiers

Key hierarchy change: T3 (facts) sits ABOVE T2 (summaries). Facts are
compact, high-value, and survive better across long conversations than lossy
summaries. When budget is tight, facts must be preserved before summaries.

Dual Policies

T3 — SEMANTIC

Storage policy:
- Preserve all valid facts canonically — never overwrite with summaries.
- Facts can be deprecated (status='superseded') but never silently deleted.
- All facts retain full provenance (source_message_id, source_span).

Prompt policy:
- Include top-K relevant facts (not all facts unconditionally).
- Rank by weighted score: prompt relevance > confidence > recency > permanence > scope match.
- Budget controlled by ORCH_CONTEXT_FACT_TOP_K.

T5 — KNOWLEDGE

Storage policy:
- Canonical. raw_content and normalized_content are never overwritten or compressed.

Prompt policy:
- May be excerpted or compressed for prompt inclusion.
- Prompt views are derived, provenance-preserving (linked via source_ref, created_from_run_id), and non-authoritative.

Safety Rules

1. T1 is never overwritten by T2. Summaries supplement raw turns; they do not replace them in storage.
2. T3 is additive-only. Facts can be added or deprecated, never silently dropped.
3. T3 must be extracted from raw T1 data, never from T2 summaries. Pipeline: raw messages/tool outputs → fact extraction → fact storage → fact retrieval.
4. T2/T4 compression is display-only. The raw source (T1/T4 payload) must remain queryable.
5. Every derived artifact must link back to source records via conversation_id + turn range or trace_id.
6. Extractive summarisation (B2) is only allowed on T4 trace display contexts.

Fact Lifecycle

Status values

Scope values (fact_scope)

Contradiction handling

When a new fact contradicts an existing one (same fact_key, different value),
the old fact is marked superseded with superseded_by pointing to the new
fact's ID and superseded_at set. The superseded fact remains queryable for
audit.

Context Pyramid

Assembly order (pyramid top = highest priority):

         ┌───────────┐
         │  T3 FACTS │  ← top-K ranked, structured section
         │ + TASKS   │
         ├───────────┤
         │ T1 RECENT │  ← 2–6 raw turns, never compressed
         │ (raw hist)│
         ├───────────┤
         │ T2 EPISOD │  ← 8–12 summaries (lossy)
         │ (summaries│
         ├───────────┤
         │ T5 KNOWL  │  ← injected by similarity, outside budget
         │ (KB/embed)│
         ├───────────┤
         │ T4 TRACE  │  ← only for debug/self-repair
         │ (telemetr)│
         └───────────┘

Prompt assembly order

1. Current user prompt
2. Recent raw turns (T1 — highest fidelity)
3. Relevant semantic facts (T3 — compact, durable)
4. Relevant tasks / goals / preferences (T3 — active tasks)
5. Episodic summaries for older history (T2 — lossy, continuity)
6. Retrieved documents / artifacts (T5 — on demand)
7. Trace hints (T4 — rarely, only for debug/repair)

Code Mapping

Source Traceability

Traceability is a test invariant, not just a design principle:

• Every conversation_facts row must have a non-null source_message_id.
• Every conversation_memory_snapshots row must have a source range or source IDs.
• Every fact packed into the prompt by ContextPacker.pack() must be traceable to a DB record.

Context Labels → Tier Classification

See backend/agents/memory_tiers.py for the authoritative CONTEXT_LABEL_TIER mapping.

Miner Pools, BYOK, and Dispatch Flows

This document describes how the miner dispatch system works: what pools exist, how BYOK (Bring Your Own Key) settings function for users and organizations, and how all of these interact during a chat or API request.

What Is a Miner?

A miner is a compute endpoint that handles model inference requests. There are two physical kinds:

• Real miners — machines running the Elis miner software. They maintain an active session and heartbeat with the platform, and receive jobs over a WebSocket dispatch channel.
• Virtual miners — database records that route a request directly to a provider API (OpenAI, Anthropic, Google, etc.) using an encrypted API key stored by the platform. BYOK miners are always virtual.

Miners are stored in the miners table. The key identity fields are:

Miner Pools

There are four distinct pool types, identifiable by the miner ID prefix and organization_id:

1. Community Pool

• ID prefix: none (e.g. a3f9b2...)
• organization_id: NULL
• Who can access: everyone — personal users and all orgs (unless the org disables it)
• Trust tier: community

Community miners are physical machines run by volunteers or infrastructure partners. They are globally shared. Any request that allows community miners can land on any of these. They sort last behind BYOK virtual miners in the scheduler and are filtered by reserved_owner_user_id = NULL.

2. User BYOK Pool (byok-)

• ID prefix: byok-
• organization_id: NULL
• owner_user_id: the registering user
• Who can access: depends on is_shared (see below)

Virtual miners that call a provider API using the individual user's encrypted key.

3. Org BYOK Pool (orgbyok-)

• ID prefix: orgbyok-
• organization_id: the owning org
• Who can access: depends on is_shared (see below)

Virtual miners that call a provider API using the org's encrypted key. Earnings settle to the org wallet via payout_company_id.

4. Org Dedicated Pool

• ID prefix: none (e.g. d7c1e4...)
• organization_id: set to the owning org
• Who can access: that org exclusively
• Trust tier: enterprise or internal

Physical machines running the Elis miner software, provisioned and operated by the organization. These are the only miners that count as "Dedicated Miners" for billing and compliance purposes.

User BYOK Settings

Enabling BYOK

BYOK is off by default and requires explicit opt-in. The setting lives in user_preferences.byok_enabled. When enabled, the platform surfaces the BYOK management UI and /miners tab.

Registering a BYOK Miner

A user registers a miner via POST /api/miners/byok/register, providing:
- provider — openai | anthropic | google | groq | mistral | cerebras
- model_name — the specific model this key will serve (e.g. gpt-4o, claude-opus-4-6)
- api_key — stored AES-GCM encrypted, never returned in responses
- label — optional display name
- is_shared — whether to contribute to the community pool (default false)

The is_shared Toggle (Share / Private)

Each user BYOK miner has an is_shared flag that can be toggled at any time via PATCH /api/miners/byok/<id>.

Shared mode (is_shared = true)
- trust_tier → community
- reserved_owner_user_id → cleared (empty)
- The miner enters the global community pool and is selectable for any user's requests
- The owner earns credits for every completed job that routes through their key
- Useful for contributing capacity in exchange for platform credits

Private mode (is_shared = false)
- trust_tier → enterprise
- reserved_owner_user_id → set to the owner's user ID
- Only requests from the key owner can select this miner
- No credit payouts (the user is consuming their own key)
- Useful for cost control — all your requests use your own key instead of the platform's

Disabled (deactivated)
- is_active = false — set automatically when the key returns a 401 or 403 from the provider
- key_error — stores the reason string from the failed response
- The miner stops accepting jobs; the UI shows the deactivation reason
- Reactivate by updating the key via PATCH /api/miners/byok/<id> with a fresh api_key

byok_only_mode

user_preferences.byok_only_mode is a per-user escalation flag. When enabled:
- Requests from this user are routed exclusively through their own BYOK miners
- The community pool and platform API keys are bypassed entirely
- Useful for users who need all inference to use their own provider account (cost attribution, compliance, etc.)
- Only meaningful when the user has at least one active private BYOK miner registered; otherwise requests will fail

Org BYOK Settings

Registering an Org BYOK Miner

Organization admins register org BYOK miners via POST /api/companies/<id>/miners/byok/register. The API and fields are identical to user BYOK, but:
- Miner ID gets an orgbyok- prefix
- The key is stored in company_miner_api_keys (separate table from user_miner_api_keys)
- Earnings settle to the org wallet via miners.payout_company_id

The is_shared Toggle for Org BYOK

Behaves identically to user BYOK sharing:

Shared (is_shared = true) — the org's key joins the community pool. Other tenants' requests can route through it. The org earns credits.

Private (is_shared = false) — scoped to organization_id. Only requests from members of this org can use it. The org is consuming its own key for its own members.

Important: An org BYOK miner is a virtual miner — it calls a provider API using your key. It is not the same as a Dedicated Miner. Org BYOK is available on all plans. Dedicated Miners require running the Elis miner software on your own hardware or cloud VMs.

Org-Level Pool Settings (companies.settings)

Two org settings control which pools requests from this org may use:

allow_community_miners (default: true)

When true, org members' requests can be served by community miners (and the platform's own API keys) in addition to the org's own miners.

When false, requests are locked to the org's own pool (dedicated + org BYOK miners). If no org miners are online for the requested model, the request fails rather than falling back to community capacity.

dedicated_miners_only (default: false)

When true (also triggered by deployment_type = "dedicated" or deployment_mode = "onsite"):
- Only the org's dedicated real miners may serve requests
- Org BYOK miners are excluded
- Community miners are excluded
- Platform API keys are excluded
- If no dedicated miner is online for the model, the request returns dedicated_miner_unavailable immediately

This is the strictest enforcement mode — it guarantees inference stays on the org's own managed hardware.

Dispatch Flow — Personal Chat (No Org)

A personal chat has user_id and conversation_id but no company_id. The dispatch logic:

1. company_id is empty → _effective_allow_community_miners("") returns true
2. effective_dedicated_miners_only is false
3. The scheduler queries list_schedulable_miners(model=..., organization_id="") which returns community miners only (organization_id IS NULL)
4. If a community miner is available for the requested model → dispatched via WebSocket
5. If no community miner is available → falls through to the platform's direct API key for that provider
6. If the user has byok_only_mode = true → only their private BYOK miners are eligible; falls through to those instead

Pool available to a personal chat: community miners + user's own private BYOK miners (if byok_enabled) + platform API key fallback.

Dispatch Flow — Org Chat

An org chat has company_id set in the run packet (injected by _packet_for_miner() in orchestration).

1. _effective_dedicated_miners_only(company_id) — resolves from companies.settings
2. _effective_allow_community_miners(company_id) — resolves from companies.settings
3. Scheduler queries list_schedulable_miners(model=..., organization_id=company_id) which returns:
   - Community miners (organization_id IS NULL)
   - This org's own miners (organization_id = company_id)
4. The scope check (_has_accessible_miner_scope) then filters:
   - If dedicated_miners_only=true → only accept miners where miner.organization_id == company_id
   - If allow_community_miners=false → reject any miner with miner.organization_id = NULL
5. If the scope check passes and a miner is dispatched → done
6. If dedicated_miners_only=true and no miner dispatched → dedicated_miner_unavailable error
7. If allow_community_miners=false and scope check fails → no_accessible_miners error
8. If allow_community_miners=true and no miner dispatched → falls through to platform API key

Pool available to an org chat depends on settings — see the matrix below.

Settings Interaction Matrix

The table below shows what pool is available for a request given the combination of org settings. "Platform API" means the platform's own provider API keys (always available as a last resort unless locked out by policy).

Community-only org (no dedicated, no BYOK, allow_community=true)
Requests go to community miners. If none online for the model, the platform API key handles it. This is the default for new orgs.

Closed-pool org (allow_community=false, dedicated_miners_only=false)
Requests stay within the org's own miners (dedicated + org BYOK). If none available, the request fails. No community exposure.

Fully dedicated org (dedicated_miners_only=true)
Requests must land on the org's own physical dedicated miners. No BYOK, no community, no platform API. Hard fail if no miner online.

Org with BYOK + community allowed (default + org BYOK registered)
Org BYOK miners are preferred (sorted before community by scheduler). Community miners fill in when no org BYOK miner is online. Platform API is final fallback.

Miner Reliability States

The scheduler tracks failures and updates miners.reliability_state:

When a BYOK key returns a 401 or 403 from the provider, the miner is deactivated (is_active = false) and the key_error field is written with the provider's error message. The UI surfaces this reason on the miner card and detail page. The miner stays deactivated until the admin rotates the key.

Narrator vs Chat Dispatch

The narrator (background task generation) builds a descriptor with an empty miner ID (provider:model#) and loops through multiple model candidates. It never hits the _has_accessible_miner_scope hard-fail because it is not dispatched through the miner WebSocket path — it goes directly to provider API.

Chat completions go through the full miner dispatch path: WebSocket first, then the scope check, then platform API fallback. This is why a personal chat could historically show "no organization miners are currently online" even while narrator responses succeeded — the scope check would hard-fail before reaching the platform API fallback if no community miner happened to be online for the exact model. That path is now fixed to fall through when allow_community_miners=true.

Key Tables

Here’s a cleaner logic-chain version:

For each setting, validate scope first:
- User settings apply only to personal chats.
- Org settings apply only to chats inside that organization.
- Org settings must not affect personal chats.

BYOK mode OFF:
- For users: personal chats can access community miners.
- For orgs: org chats can access community miners.

BYOK mode ON + private/share-restricted mode:
- For users: only that user can access their BYOK miners.
- For orgs: only that org can access its BYOK miners.

BYOK mode ON + community share mode:
- For users: the user’s BYOK miners are added to the community pool.
- For orgs: the org’s BYOK miners are added to the community pool.
- Once added to the community pool, everyone can use those miners.

BYOK-only mode:
- For users: personal chats must only use that user’s BYOK miners.
- For orgs: org chats must only use that org’s BYOK miners.

Scope enforcement:
- Org miner settings are only valid inside that organization’s chats.
- Org miner settings cannot impose behavior on personal chats.
- Personal chats must use the user’s own miner settings.

Documentation
Learn how the Elis AI distributed intelligence network processes your requests.
How Elis AI Works
Elis AI is a distributed intelligence network that breaks complex questions into smaller, focused tasks and routes them to specialized AI agents running across a decentralized pool of compute miners. Instead of relying on a single large model, every request passes through a dynamic pipeline that picks the best-fit agent, dispatches inference to the best available miner, and returns a fully traced answer — so you always know how a response was produced.
🤖 Elis AI Mode
Automatically builds and reuses specialized agents. Each agent runs a multi-step workflow — expertise lookup, context retrieval, execution — using the best available model tier for each step.
🔓 Elis Unlocked
Advanced multi-pass workflow with planning, fact-checking, and iterative refinement. Best for complex tasks that need verification and deep research.
⛏️ Miners
Miners host local LLMs and earn tokens for verified responses. The network supports multiple model tiers for speed and quality tradeoffs.
🛡️ Verification
Every inference step is traced end-to-end. The scheduler selects the best available miner using weighted round-robin, trust tiers, and load awareness — ensuring fair distribution and reliable execution.
Why the network stays sustainable
Elis is built on a token economy where compute contributors are rewarded for useful work. Miners that return high-quality results quickly earn more assignments. Because miners compete regionally, users get served by nearby high-performing nodes — improving latency and experience.
For Consumers
Contribute background compute to earn tokens that offset usage costs.
Background contribution earns tokens.
Tokens are spent on model and tool usage.
Quality verification keeps rewards fair.
For Enterprise
End-to-end encryption, automated PII redaction, audit trails, and self-hosted deployment options. See Enterprise section →
Process Flow
1. User submits prompt → 2. Router chain selects agent → 3. Agent builds workflow → 4. Miners run inference → 5. Quality verification → 6. Traced response returned
Ready to try it?
Create an account and start asking questions — every answer comes with a full trace.
Get Started → View Whitepapers

Guided Walkthroughs
Tutorials shaped like the landing page, but built for real product work.
Step-by-step guides to help you get the most out of Elis AI. Choose the track that matches how you use the platform.
User Guide
For everyone. Learn how to use the platform day to day, set up teams, and manage the resources tied to your workspace.
Sign Up & Log In
Create your account and access the platform.
Open
Starting a Conversation
Send your first prompt and see AI responses stream in.
Open
Document Editor
Writer documents (50 cap), AI rewrite & selection tools, links, merge, history, and side chat.
Open
Managing Messages
Edit, resend, copy, and delete messages.
Open
Creating an Organization
Set up an organization to collaborate with your team.
Open
Managing Members
Invite team members, set roles, and manage access.
Open
Uploading Documents
Upload files for your organization's knowledge base.
Open
Connecting Databases
Link an external database for context-aware queries.
Open
Creating & Managing Projects
Organize work into projects with linked resources.
Open
Viewing the Audit Log
Review all activity within your organization.
Open
Settings & API Keys
Manage your profile and create API keys.
Open
Billing & Tokens
Purchase token packages and view transaction history.
Open
Subscription Management
Cancel or restore personal and organization subscriptions before access changes take effect.
Open
Organization Seat Management
Lower seat blocks safely by choosing which members or pending invites lose access.
Open
Browsing Models
Explore the model directory and compare options.
Open
Accepting Invitations
View and respond to pending organization invites.
Open
Project Conversations
Create and manage conversations within a project context.
Open
Using Dashboards
Create dashboards, iterate drafts, publish versions, and manage favorites.
Open
AI Edit a Dashboard
Edit dashboards in plain English with a live preview, clarify questions, and per-message restore points.
Open
Dashboard Editor Deep Dive
Understand each editor section: planning, AI spec edits, tasks, buckets, datasources, draft thread, and assistants.
Open
Using Automations
Organization-only recurring widgets with mobile support, chart modes, and alert dispatch.
Open
Deep Data Collection
Crawl websites, extract structured records, share public datasets, and earn credits.
Open
Enterprise & Dedicated Hosting
Enterprise
Dedicated infrastructure, model governance, BYOK/BYOA credentials, organization-scoped miners, and lifecycle operations for enterprise deployments.
Dedicated Hosting Upgrade
Activate dedicated deployment, select shared vs. dedicated at org creation, and monitor cluster provisioning lifecycle.
Open
Dedicated User Management
Invite members with cluster-aware links, review pending signup invites, and adjust paid seat capacity without losing track of reserved seats.
Open
Enterprise Controls
Configure model allow/block lists, web domain allowlist, BYOK API keys, and BYOA OAuth credentials.
Open
Provider API Keys (BYOK)
Sign up with OpenAI, Anthropic, Google, Groq, Mistral, and Cerebras, then store each provider key on your organization.
Open
Dedicated Miners
Assign organization-scoped miners, generate registration tokens, and enforce dedicated-only inference.
Open
OAuth & SSO Setup
Configure BYOA OAuth credentials and optional SSO enforcement for enterprise cluster members.
Open
Dedicated Lifecycle Operations
Operate Stripe webhook lifecycle, grace mode, data export, and cluster decommission procedures.
Open
Developer Guide
For admins and developers. Go deeper on miner management, API integration, observability, and operator tooling.
On-Prem Installation
Purchase the annual license, download the Docker bundle, install dependencies, and activate the platform.
Open
Setting Up a Miner
Hosted or self-hosted: BACKEND_URL, MODEL_NAME, pairing key, Docker or Windows.
Open
Managing Miners
Monitor health, filter workers, enable/disable, validate pairing, unclaim when needed.
Open
Using the API
Authenticate and make programmatic requests.
Open
Automations API
Create, run, and monitor recurring research widgets via REST.
Open
Conversation Explorer
Browse and filter conversations with run telemetry.
Open
Agent Directory & Detail
Search agents, view stats, and explore mutations.
Open
Runs Dashboard & Comparison
Filter runs and compare them side by side.
Open
Run Detail Deep Dive
Inspect Overview, Routing, Steps, Context, and Integrity tabs.
Open
Anomaly Dashboard
Filter by anomaly type and severity, then drill into flagged runs.
Open
Downloads
Access compiled packages and Docker images.
Open