Integrate AI with the physical environment

ALYT is a local-first layer between applications, AI systems, operators, and the physical environment. Your integration reads ALYT’s current inventory, rooms, capabilities, routines, and permissions, then acts only through the authorized public interfaces for that home. ALYT remains the authority for state, deterministic execution, and physical outcome confirmation, so model output, device names, and external descriptions are treated as data rather than permission or transport instructions. Use the current developer portal flow for DEV and LIVE only, and keep cloud-dependent behavior out of the physical control path.

Start with an authorized installation

Use the developer portal credentials and current API reference for authentication and available public operations.

• DEV credentials operate in the developer sandbox.
• LIVE credentials act only within their installed connector’s scope.

Do not treat developer access as general access to customer homes. A developer account, a partner visit, and ordinary household membership have different authority. Household permissions are narrower than staff.

Bind every request to both the tenant and the selected home. Resolve room, device, endpoint, and routine identity from ALYT instead of matching by display name alone. Names can repeat across rooms and homes. Recheck access whenever a user changes home or loses membership.

Follow the current API reference instead of guessing an AI endpoint. Private proposal and ledger interfaces are not public SDK routes. DEV and LIVE credentials cannot call private context, proposal or ledger interfaces.

Build against capabilities, not names

Read the descriptors and actual supported controls, then render what ALYT provides:

• writable or read-only status
• numeric range and step
• options
• units
• state versus settings binding

A read-only sensor stays read-only. Keep requested values separate from observed values.

Use normalized capabilities across manufacturers. The catalogue helps identify models and setup requirements, but it does not grant control and does not imply that every manufacturer-specific feature is exposed. Do not derive unsupported private commands from a device name, description, or model response.

Keep AI behind the platform boundary

An application or other AI can interpret a user request, summarize context, or draft intended actions. ALYT owns control boundaries.

That means you should:

• constrain generated intent to operations your integration is authorized to perform
• treat names, provider descriptions, web content, and model output as untrusted input
• never pass raw transport access, connector credentials, or unrestricted execution tools to a model

An AI conversation is not the inventory and is not a grant of control. Use ALYT’s saved routine identity and existing routine interface. Do not recreate a routine from its name or build a parallel executor.

Any approval must stay bound to the exact requested action. If the action changes, approval must be obtained again.

Use public context and routine operations

For physical context, use the ordinary public capability and routine operations exposed in the API reference. Do not rely on internal-only validation, ledger, or context routes from ALYT runtime documentation. DEV and LIVE credentials cannot call private context, proposal or ledger interfaces.

When ALYT returns context, keep it bounded and pinned to the current home and current revision. Query references and pagination cursors are tied to a pinned context. If the context changes or expires, request a new one instead of reusing stale references.

Context limits

Limit	Value
Maximum rooms	32
Maximum entities	64
Maximum controls	128
Maximum observations	128
Maximum routines	16
Maximum hypotheses	8
Maximum goals	8
Maximum effects	8
Maximum preconditions	16
Maximum history window	3,600,000 ms
Maximum payload size	65,536 bytes
Context lifetime ceiling	300,000 ms

Paged local context readers also keep bounded cursor state and can return omitted sections when byte or node budgets are exceeded. If a byte budget cannot fit the requested page, increase maxBytes and request again.

Understand evidence and confirmation

Accepted delivery, transport acknowledgement, and observed physical outcome are different facts.

Do not report success because:

• a model said it succeeded
• transport accepted a command
• some other capability changed

A requested change is confirmed only by admissible device evidence for that change. Keep pending, failed, partial, and unknown states visible to the operator.

If an effect is uncertain, reconcile current state or ask the operator before repeating a consequential action. Preserve newer manual changes during recovery.

Observation and journal limits

Limit	Value
Fields per report	64
Fields per endpoint snapshot	128
Event payload bytes	32,768
Snapshot bytes	65,536
Events retained per home	4,096
Event retention window	259,200,000 ms
Replay events per packet	32
Event claim batch	32
Event lease	30,000 ms
Retry delay maximum	300,000 ms

If retained history is trimmed or a source gap is detected, ALYT can mark history as incomplete and require a fresh snapshot instead of replay.

Respect execution ownership and exact intent

For actions with physical effects, ALYT may bind execution to the exact approved effect, owner, home, and expiry. The useful developer rule is straightforward: send only the exact action ALYT authorized, against the exact target ALYT identified, within the lifetime ALYT gave you.

Do not mutate the payload after approval, and do not replay consequential writes when ALYT marks them as non-replayable or expired. Routine and device execution can require exact installed versions and exact target ownership at send time.

This matters especially for connectors that bridge into a hub or provider-specific owner path. A prepared effect can be authorized before any physical outcome is observed, and confirmation remains separate from execution.

Respect placement and outage boundaries

Device execution, app hosting, state storage, voice processing, and model inference are separate placement decisions.

Local control does not prove local inference. Some ALYT functions continue during cloud loss because the platform is local-first, but not every connector does.

• Local functions can keep working during a cloud outage.
• Local routine steps execute in the home.
• cloud-dependent connectors require their provider and network.

Never claim a cloud connector still works when its provider path or network path is unavailable.

For example, a locally routed hub-owned light path may continue working during a provider outage, while a cloud music or camera path may not. Verify the installed route and current home configuration before you describe available behavior.

Minimize exported context

Before sending household context to a model or external provider:

• verify the current configuration and consent
• minimize data
• exclude credentials
• exclude private media
• exclude unnecessary household information

Opening an inventory or context view is a read, not a physical probe or command.

Related guides

Use the portal’s device model, capability, credentials, routine, and deployment guides together with the API reference for concrete request and response details.