Symbolic and LLM routing pipeline

How Arka’s layered pipeline routes natural language to 120+ skill patterns using symbolic offline matching before falling back to an LLM.

Arka routes every request through a layered pipeline. Most requests never touch an LLM — symbolic rules in config.fish match 120+ skill patterns offline.

Important: if you type a plain shell command, the shell runs it normally. Arka only gets a chance to route the request when you invoke it through arka or an alias like agent_route.

Routing pipeline

1. Direct skill name

   If the first token matches a registered skill, Arka runs it immediately. Zero tokens.

   arka weather
   arka calc 2+2
   demo_echo hello    # third-party plugin by name
   
2. Plugin triggers

   Arka checks third-party skills in ~/.config/arka/skills/ next. Each plugin declares triggers in skill.json.

3. Offline symbolic rules

   The default path. _agent_guess_route and _agent_offline_route_cmd in config.fish match regex patterns for 120+ skills. No LLM call. You’ll see 💡 [Offline routing] and → Interpreted: … when this fires.

4. LLM route

   When offline rules don’t match, Arka sends a compact skill catalog to the LLM with task=route. The model picks the best skill.

5. Correction layer

   A deterministic correction layer fixes weak LLM picks without a second LLM call (e.g. search_web → web_answer for factual questions).

6. Dispatch

   dispatch.py executes the chosen skill script.

Token usage by layer

Layer	LLM tokens
Direct skill name	0
Symbolic routing	0
Plugin triggers	0
LLM route (fallback)	small (compact catalog only)

Default mode is ROUTE_MODE=symbolic — offline rules first, AI only when needed.

Ambiguous routing

When two or more offline patterns could apply (common with play/media), Arka detects the collision and asks the LLM to choose:

💡 [AI routing — ambiguous play/media request]
→ Interpreted: play_movie bohemian rhapsody

Clear one-sided requests still use offline routing with zero tokens.

Route modes

Mode	Behavior
symbolic	Offline rules first, LLM only when needed (default)
ai	Prefer LLM routing
symbolic_only	Never call LLM for routing; Python symbolic extras run before fish, and fish LLM previews are ignored
ai_only	Always use LLM for routing

ROUTE_MODE=symbolic

Inspect routing

Preview what skill Arka would pick without running it:

arka route "summarize my unread emails"
agent_route "play bohemian rhapsody on spotify"
agent_trace          # last routing decision
agent_why            # explain skill choice
arka help            # full skill list
arka tell your skills   # voice-friendly summary + active model

Python fallback (no fish)

When fish is not installed, Arka uses src/arka/routing/symbolic.py for the same offline-first behavior. The portable CLI still supports chat, web answers, passwords, calc, weather, sports, and plugins.

Install fish shell to unlock the full 70+ skill router.

The self-improve workflow is also routed as a dedicated skill, so phrases like self improve routing can stay local and deterministic while still opening the repo analysis path.

Developer tooling now follows the same offline-first path: arka ci, arka review staged, route audit, and skill new my_tool --template dev are handled by symbolic routing before any LLM fallback.

For UI work, build this project from screenshot.png and similar phrases route to the screenshot-to-design brief skill, which analyzes the image first and then produces an implementation-oriented build plan.

If you want Arka to look at its own frontend output and iterate, phrases like review this frontend, retry 3 loops, or check the UI screenshot and rebuild route to the frontend visual loop skill. It captures the rendered result, critiques it, and can run another build command before the next pass.

Skill router vs orchestrator

The skill router decides which skill runs. The LLM orchestrator (see LLM orchestration) powers completions inside skills — summarize, chat, research, PDF, predictions — with provider failover. They are separate systems.

Related