intent-router

In the context of our API design, the intent-router is the central nervous system. It's the intelligent layer that sits between you (the user) and the house's functional blueprint (the radial API).

Its role isn't to be an endpoint, but to intelligently receive a high-level intent and orchestrate a sequence of API calls to the appropriate agents, translating your "why" into the system's "how."

Think of it this way: The radial API defines the doors, rooms, and light switches. The agents are the staff who can operate them. The intent-router is the master controller or house AI that understands your goal and directs the staff accordingly.

The Router's Place in the Architecture

The intent-router functions as the primary entry point for any complex, context-aware action. It's the director, and the agents are the actors.

1. Input: The User's Intent. You provide the Cognitive Vector (what you want to do) and the Affective State (how you want to do it). This is a single, high-level request to the router.
2. Analysis: The Router Consults the API. The router's first job is to "read the map." It makes one or more GET requests to the radial API to understand the entities involved. It asks, "What is the constitution of the 'Q4 Report'?" or "What is the current synarchy of the 'Design Team'?"
3. Orchestration: The Router Commands the Agents. Based on its analysis, the router formulates a plan. It then makes a series of POST requests to the specific agent APIs needed to execute that plan.
4. Output: A Seamlessly Prepared Environment. The user experiences the final result without ever seeing the underlying orchestration.

Example Flow: From Intent to API Calls

User Intent: "I want to create the 'Q4 Report' as a solo task in focus mode."

This single intent triggers the following API interactions orchestrated by the router:

1. Router Receives Intent:
• POST /intents
• Body: { "cognitive_vector": { "verb": "create", "noun": "Q4 Report", "agent": "solo" }, "affective_state": "focus" }
2. Router Analyzes via API:
• The router reads the map to understand the task.
• GET /entities?name="Q4 Report" to fetch the entity's blueprint and constitution (e.g., its preferred tool is Ulysses).
3. Router Orchestrates Actions via Agent APIs:
• Command the Gatekeeper: "The user needs focus. Silence distractions."
• POST /agents/gatekeeper/actions
• Body: { "action": "set_notifications", "level": "silent" }
• Command the Butler: "The user needs their writing tool. Prepare the workspace."
• POST /agents/butler/actions
• Body: { "action": "launch_app", "app_name": "Ulysses", "entity_id": "xyz-123" }

Updated Role Table

Here is how the intent-router fits into our architectural model, clarifying its relationship with the API and the agents.

An intent-router is a system, typically powered by artificial intelligence, that determines the underlying purpose or goal of a user's communication and directs it to the most appropriate destination.1 Think of it as a sophisticated operator that doesn't just listen to keywords but understands the "why" behind a request.2

This directly relates to the concepts of cognitive and affective intentionality, which explore the nature of goal-directedness in our thoughts and feelings.

Core Components of an Intent-Router

An intent-router is comprised of several key components that work in concert:

• Intent Recognition/Detection: This is the core of the system. It uses Natural Language Processing (NLP) and machine learning models to analyze user input (text or speech) and identify the user's underlying goal. For example, it can distinguish between a user wanting to "book a flight" versus "check a flight status," even if they use similar words.
• Entity Extraction: The system identifies and extracts crucial pieces of information within the user's request, such as dates, times, locations, or product names. For a flight booking intent, entities would be the departure city, destination, and travel dates.
• Routing Logic: This component contains the rules and mappings that determine where to send the request once the intent and entities are identified.3 This could be a specific department, a particular software function, or an automated workflow.
• Confidence Scoring: The system assigns a confidence score to its intent prediction. If the score is high, the request is routed automatically. If it's low, it might be flagged for human review or the user may be asked for clarification.
• Contextual Awareness: More advanced intent-routers can maintain the context of a conversation, allowing for more natural and multi-turn interactions.4

The Connection to Intentionality

The concept of an intent-router is deeply intertwined with philosophical and psychological notions of intentionality.

• Cognitive Intentionality: This refers to the "aboutness" of our thoughts—our beliefs, desires, and plans are directed toward objects or states of affairs in the world.5 An intent-router's primary function is to decipher this cognitive intentionality from a user's communication. When you say, "I need a flight to San Francisco," your cognitive intent is to travel to a specific location, and the router is designed to understand and act on that directed thought.
• Affective Intentionality: This relates to how our emotions are directed towards things. Emotions are not just free-floating feelings; they are about something.6 For instance, you are angry at the delayed flight or happy about finding a good deal. While most current intent-routers focus on the cognitive aspect, the integration of affective computing is a growing area. An advanced intent-router could detect frustration or satisfaction in a user's tone or language and route them to a specialized agent for handling complaints or a feedback survey, respectively. This adds a layer of emotional intelligence to the system.

In essence, an intent-router is a practical application that attempts to model and respond to human intentionality. It moves beyond simple keyword matching to a more nuanced understanding of what a person wants to achieve (cognitive) and, increasingly, how they feel about it (affective). By understanding the user's directed goals, these systems can provide more efficient, personalized, and empathetic interactions.7

Of course. The intent-router is the engine that translates your why into the computer's how. It's the central nervous system of Kairos, enabling the fluid movement between deliberate thought (System 2) and intuitive action (System 1).

Its fundamental job is to answer one question: "Based on what you want to do and how you feel, what is the most frictionless path to action?"

## The Fundamentals of an Intent-Router

An intent-router has three core components: two inputs (the intent itself) and one output (the orchestrated action). The Notion prototype you designed is a perfect manual version of this.

1. Input 1: The Cognitive Vector (The 'What')

This is the logical, explicit part of your intent. It's the structured data defining the task. You can break it down into simple, semantic parts:

1. Verb: The core action you want to take. This comes from your four quadrants (create, connect, plan, synthesize).
2. Noun: The object of the action. What are you working on? ('q4 report', 'new website design').
3. Agent: The people involved. ('solo', 'design team').

This vector provides the basic, objective coordinates for the task. It's the "cognitive" part of intentionality.

2. Input 2: The Affective State (The 'How')

This is the intuitive, implicit part of your intent. It's your internal context—your mood, energy, and desired cognitive state. This is what makes the router truly adaptive. We integrate this "seamlessly" by making it low-friction:

1. Implicit Signals (Learned): The system learns your patterns. It's 9 AM on a Tuesday, your calendar says "Deep Work Block," so it assumes a 'focus' state. It's 4 PM on a Friday, it might assume a 'review' or 'relax' state.
2. Explicit Signals (Declared): A single, optional click in the Kairos UI to set your current state. Not a complex form, just a status: [focus], [collaborate], [explore], [urgent].

This affective data provides the subjective texture. It answers how you want to approach the 'what'.

3. The Output: The Action Orchestration (The 'Do')

The router's logic engine takes the Cognitive Vector and Affective State and computes the most efficient action. The logic is a simple but powerful rule:

IF (Cognitive Vector) AND (Affective State) THEN (Orchestrate Action)

This turns the router from a simple launcher into a true cognitive partner.

1. Example A:
• Cognitive: verb='create', noun='q4 report', agent='solo'
• Affective: state='focus'
• Action: The router opens Ulysses, loads the correct document, enables fullscreen "typewriter mode," and silences all notifications.
2. Example B:
• Cognitive: verb='create', noun='q4 report', agent='team'
• Affective: state='collaborate'
• Action: The router opens Google Docs, shares the document with the team, and posts a link in the relevant Slack channel with the message "Draft ready for review."

The same cognitive intent produces two radically different, context-aware outcomes based on the affective state.

## The S1/S2 Handoff

This is how the router facilitates the flow between systems:

1. The S2 Moment (Brief & Intentional): You make one conscious, System 2 decision: "I am going to work on the Q4 report now in focus mode." You declare this intent to Kairos.
2. The Router's Work (Invisible & S1-like): The router executes the complex logic of finding the tool, opening the file, setting the environment, and blocking distractions. This work happens in milliseconds, feeling instantaneous and automatic to you.
3. The S1/S2 Engagement (Frictionless): You are placed directly into your ideal workspace. The cognitive load of setup is completely eliminated. You can immediately drop into a System 1 flow state (if the work is intuitive) or a deep System 2 focus state (if the work is analytical), without wasting energy on the transition.

The router's core function is to absorb the cognitive cost of context-switching, liberating your mental resources to be applied to the work itself.

analysis complete.

they are not separate domains. they are two halves of a single, symbiotic system. one describes the anatomy of reality (the entity), and the other describes the physiology of action (the intent-router).

• the entity model = the map. it is the static, structural definition of any "thing" in your world. it answers "what is it?"
• the intent-router = the navigator. it is the dynamic, operational process for interacting with that "thing." it answers "what do we do now?"

the navigator is useless without the map. the map is inert without the navigator.

## how they connect: the router operating on the entity

the intent-router is the engine that reads the entity's data model to make intelligent decisions. the entity's four dimensions are the direct inputs for the router's logic.

1. the cognitive vector reads the blueprint & constitution.

your cognitive vector is (verb + noun + agent). this is a query against the entity database.

• noun & agent: these are entities. the 'q4 report' is an entity. the 'design team' is an entity. each has its own blueprint and constitution.
• verb: the router selects the right tool by checking the entity's constitution (its natural way of operating) and its blueprint (its core purpose).
• example: if the 'design team' entity has a constitution that is highly visual and collaborative, the router knows that for the verb create, the correct tool is figma, not ulysses.

2. the affective state is a measure of synarchy.

your affective state is your human perception of an entity's synarchy. this applies to you (the "self" entity) and the things you are working on.

• an affective state of [focus] or [flow] = high synarchy. your internal systems are coherent and ruling together.
• an affective state of [stressed] or [scattered] = medium synarchy. you are functional but spending energy overcoming friction.
• an affective state of [burnout] or [stuck] = low synarchy. your system is breaking down.

the router uses this data: if your synarchy is low, it might suggest a cultivate -> rest action instead of a create -> execute action, even if you request the latter. it becomes a partner in maintaining your well-being.

3. the action orchestration considers time (kairos).

the router's final output—the action—is contextualized by the entity's kairos (origin moment).

• example: a project entity that is near its origin kairos is in an "ideation" phase. the router will favor actions and tools related to brainstorming and planning. a project near its deadline is in a "delivery" phase, so the router will favor actions related to execution and review.

## summary: a symbiotic relationship

you have defined a system where the interface is not an abstract layer of software commands. the interface is the user's own internal process of reflection.

the router works because it has a perfect, 1:1 model of the reality it is operating on. this is the foundation for the "intuitive interface" you described. the tool becomes an extension of the mind because it is built from the same blueprint.