Skip to main content

Design Decisions & Rationale

During the development and testing of Console V2 (Weave), several critical architectural pivots were made based on real-world enterprise requirements. This document records the primary engineering decisions, decommissioned components, and underlying rationale.

1. Pivot from Vertical Personas to Process Graphs​

The Initial Hypothesis (Console V1)​

Console V1 modeled enterprise automation as a collection of vertical, persona-driven agents: Marketer, BusinessFinder, Newsletter, Finance, Governance, Maintenance, and RiskDetection. Each agent had its own persona prompt, dedicated tools, and separate background worker.

Operational Problems Observed:​

  • Duplicated Integrations: Each vertical agent maintained redundant connectors for email, Slack, databases, and LLM APIs.
  • Unpredictable Trajectories: Free-form conversational agents suffered from trajectory drift during multi-step business operations, making compliance auditing extremely difficult.
  • Orchestration Bottlenecks: Composing cross-departmental operations (e.g., risk detection triggering an invoice freeze followed by client notification) required awkward agent-to-agent message passing.

The Decision (V2.5 / V2.6):​

Vertical agent personas were retired. The primary unit of work became the Process—a tenant-scoped, versioned graph of steps executing as a ProcessRun.

  • Capabilities as Skills: Capabilities from the retired vertical agents were extracted and consolidated into ~95 first-class skills registered on a centralized SkillRegistry.
  • Steps Invoke Capabilities: Process steps (20 distinct step types) invoke tools, skills, or model reasoning deterministically as part of an explicit workflow graph.
  • Single Surviving Vertical: Monica was retained as the sole surviving vertical, serving as a dedicated customer-facing support surface (monica/ app) with FAQ RAG, dispute intake, and embeddable web chat.

2. Decommissioning the Agent Marketplace (Decision Record V2.6)​

The Marketplace Model (Console V1)​

Early designs featured an in-platform "Agent Marketplace" where organizations could browse, rate, and install pre-packaged agent personas and community workflow templates (TenantAgentModel, MarketplaceRating).

The Decision to Decommission:​

In October 2026, the marketplace was permanently decommissioned and removed from routing:

  • Enterprise Reality: Enterprise customers required bespoke, auditable internal business processes integrated with existing ERPs and databases, rather than third-party public agent packages.
  • Surface Reduction: Removing the marketplace authoring UI eliminated extensive maintenance overhead and vulnerability surfaces.
  • Process Composition Substrate: The platform replaced marketplace authoring with the Process Composer (/api/processes/compose/), enabling tenants to draft deterministic business processes from natural language specifications or versioned templates.

3. Preserving Execution Endpoints for Step Capabilities​

When the tenant agent authoring surface was decommissioned, the runtime execution endpoints (/runtime/execute/<agent_id>/ and /runtime/status/<agent_id>/) were intentionally preserved.

Rationale:​

  • These endpoints serve as the internal execution layer for the process engine.
  • When a ProcessStep of type agent executes, it passes an opaque capability ID. The AgentManifest resolves this ID via a capability-agnostic fallback, allowing steps to invoke underlying model execution loops without requiring hardcoded, named personas.

4. Pluggable Memory Provider Line​

A frequent failure mode in vector-augmented agent architectures is tight coupling between the reasoning loop and external vector databases.

The Decision:​

Console V2 introduced the MemoryBus and MemoryProvider abstraction:

  • Nothing above the memory provider boundary imports brainbox/ directly.
  • The runtime queries a MemoryProvider interface.
  • If BrainBox (or its underlying PostgreSQL pgvector instance) experiences high latency or downtime, the runtime falls back gracefully, allowing process runs to proceed without crashing.

5. Fail-Closed Multi-Tenancy & Lightweight Principals​

Fail-Closed Tenant Resolution​

Multi-tenant security was built on a fail-closed cascade that never relies on client-provided IDs:

tenant = (
    getattr(request, 'tenant', None)
    or getattr(request.user, 'tenant', None)
    or getattr(getattr(request.user, 'profile', None), 'tenant', None)
)
if not tenant:
    return MyModel.objects.none()  # NEVER .all()

Lightweight Authentication Principals​

To maximize request throughput, custom authenticators return lightweight principal objects (JWTUser, APIKeyUser) instead of querying the database for a full User model on every call. Because Django ORM foreign keys type-check on assignment, the platform mandated accounts.authentication.resolve_django_user() whenever assigning a user to a model foreign key, preventing runtime assignment errors.