kunthawat/ALwrity
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
codex/replace-local-cache-with-shared-cache
ALwrity/docs/SIF/SIF_AGENTS_TEAM_ARCHITECTURE.md

9.7 KiB
Raw Permalink Blame History

SIF AI Agents Team - Architecture & Capabilities

Last Updated: 2025-03-01 Component: Semantic Intelligence Framework (SIF) Agents

🧠 Executive Summary

The SIF Agents Team is a multi-agent system built on top of the Semantic Intelligence Framework (SIF). Unlike generic AI assistants, these agents are "grounded" in a shared semantic index (txtai) containing the user's content, competitor data, and search console metrics.

Each agent acts as a specialized "Department Head," continuously monitoring the index to surface insights, propose tasks, and execute workflows autonomously.

🏗️ Architecture

The "Committee" Model

Instead of a single "God Mode" AI, we use a committee of specialized agents orchestrated by a central Manager.

graph TD
    A[User / Dashboard] -->|Requests| B(Orchestrator)
    B -->|Delegates| C[Strategy Architect]
    B -->|Delegates| D[Content Strategist]
    B -->|Delegates| E[SEO Specialist]
    B -->|Delegates| F[Social Manager]
    B -->|Delegates| G[Competitor Analyst]
    
    C & D & E & F & G -->|Reads/Writes| H[(SIF Semantic Index)]
    H -->|Syncs| I[Google Search Console]
    H -->|Syncs| J[Competitor Content]

Shared Brain (SIF Index)

All agents share the same memory (the SIF Index).

  • Example: If the Competitor Analyst indexes a new rival blog post, the Content Strategist immediately sees it as a "Content Gap" without needing a manual update.

🤖 The Agent Roster

1. Strategy Architect Agent (Lead)

  • Role: The "VP of Content." Responsible for high-level direction.
  • Key Capabilities:
    • Pillar Discovery: Clusters content to find de-facto pillars.
    • Strategy Health: Warns when content deviates from core goals.
    • Planning: Proposes quarterly themes based on performance.
  • SIF Integration: Queries txtai for cluster density and topic coherence.

2. Content Strategist Agent (Creative)

  • Role: The "Editor-in-Chief." Focuses on what to write next.
  • Key Capabilities:
    • Gap Analysis: Identifies topics competitors cover but you don't.
    • Trend Spotting: Detects rising keywords in the industry.
    • Brief Generation: Creates detailed outlines for writers.
  • SIF Integration: Compares user vector space vs. competitor vector space.

3. SEO Specialist Agent (Technical)

  • Role: The "Technical SEO." Ensures visibility and health.
  • Key Capabilities:
    • Rank Monitoring: Watches SERP movements for key pages.
    • Health Checks: Flags 404s, slow pages, or missing meta tags.
    • Opportunity Finding: "Low hanging fruit" (e.g., high impression, low CTR).
  • SIF Integration: Analyzes GSC performance data mapped to content embeddings.

4. Social Manager Agent (Engagement)

  • Role: The "Social Media Manager." Handles distribution and community.
  • Key Capabilities:
    • Repurposing: Turns blog posts into LinkedIn threads/Tweets.
    • Schedule Optimization: Predicts best times to post.
    • Engagement: Drafts replies to high-value comments.
  • SIF Integration: Matches social trends to existing content library.

5. Competitor Analyst Agent (Intelligence)

  • Role: The "Spy." Watches the market 24/7.
  • Key Capabilities:
    • Change Detection: Alerts when a competitor updates their pricing or homepage.
    • Counter-Strategy: Suggests moves to block competitor launches.
  • SIF Integration: Continuously indexes competitor sitemaps into the shared brain.

🛠️ Technical Implementation

Base Agent Interface

All agents inherit from BaseALwrityAgent and implement standard methods:

class SpecializedAgent(BaseALwrityAgent):
    async def propose_daily_tasks(self, context) -> List[TaskProposal]:
        # Domain specific logic
        pass

    async def analyze_sif_data(self, query) -> Dict[str, Any]:
        # Semantic search logic
        pass

Task Proposal Protocol

Agents don't just "chat"; they submit structured TaskProposal objects:

  • Title: Actionable name.
  • Priority: High/Medium/Low.
  • Reasoning: "Why?" (e.g., "Because competitor X did Y").
  • Source: Agent Name (displayed in UI).

📊 UI Visibility

The agents are visible to the user in three key areas:

  1. Team Huddle Widget: Real-time status (Active/Thinking) in the Main Dashboard.
  2. Today's Tasks: Each task card shows the agent's badge and reasoning.
  3. SEO Dashboard: Insights are tagged with "Identified by [Agent Name]".

🤝 Team Huddle (System Contract)

The Team Huddle is the canonical operational surface for multi-agent coordination. It must stay consistent across dashboard widget, notifications, and the full activity view.

Event/Data Contract

All orchestration updates are emitted as typed records under a shared schema:

  • status
    • agent_id, state, started_at, last_heartbeat_at, run_id?
    • State enum: idle, running, blocked, waiting_approval, degraded.
  • run
    • run_id, workflow_type, trigger, started_at, ended_at, duration_ms, outcome
    • Trigger enum: scheduled, manual, event_driven.
  • event
    • event_id, run_id, agent_id, event_type, severity, summary, created_at, metadata
    • Event type enum: insight, task, system, handoff.
  • alert
    • alert_id, event_id, threshold_key, threshold_value, observed_value, created_at, is_acknowledged
  • approval
    • approval_id, run_id, action_label, requested_by, requested_at, expires_at, approval_state
    • Approval state enum: pending, approved, rejected, expired.

Refresh + Stream Semantics

  • Primary transport is SSE with incremental delivery for each record type.
  • Clients bootstrap with latest N (default 50) records, then subscribe for deltas.
  • On disconnect: exponential backoff reconnect; if retries exhausted, switch to 15-second polling.
  • Feed ordering is deterministic by created_at DESC, tie-broken by event_id.
  • Duplicate prevention uses idempotency key = event_id (status events key by agent_id + last_heartbeat_at).

Latency SLOs

  • P50 ingest-to-UI: <= 2s for status/event.
  • P95 ingest-to-UI: <= 5s for all non-bulk events.
  • Critical alert propagation: <= 3s P95.
  • Approval decision reflection: <= 2s P95.

Failure + Fallback Behavior

  • If ingestion pipeline lags, emit synthetic system event with severity warning to inform users.
  • If an agent misses two heartbeat windows, transition status to degraded and suspend dependent handoffs.
  • If schema validation fails, route to dead-letter queue and emit sanitized system placeholder event.
  • If transport unavailable, UI remains functional in read-only cached mode with manual refresh controls.

User Detail Tiers + Security Constraints

  • Tier 1: Summary — agent, summary, timestamp, severity.
  • Tier 2: Operational — run context, thresholds, workflow outcome, approval state.
  • Tier 3: Diagnostic — trace/correlation IDs, retry counters, raw sanitized metadata.
  • Role mapping:
    • Workspace Member -> Tier 1
    • Analyst/Editor -> Tier 1-2
    • Admin/Owner -> Tier 1-3
  • Security rules:
    • Secrets, credentials, API keys, and personal identifiers are redacted before persistence.
    • Tier 3 data is never included in default exports or external webhook mirrors.
    • Approval actions require explicit authorization and audit logging of actor + timestamp.

Acceptance Criteria: View Full Team Activity

  • The "View Full Team Activity" control navigates from widget to a dedicated timeline route and preserves filters.
  • The timeline supports filtering by agent, event type, severity, status, and approval state.
  • Minimum visible fields per row:
    • event_id, created_at, agent_id, event_type, severity, summary
    • run_id, workflow_type, outcome
    • alert_id (when present), approval_id + approval_state (when present)
  • Row expansion reveals Tier 2 details; Tier 3 panel is visible only for admin/owner roles.
  • Inline interactions:
    1. Acknowledge/unacknowledge alerts.
    2. Approve/reject pending approval requests.
    3. Jump from event row to related task/insight detail.
  • Navigation continuity: returning to dashboard restores previous Team Huddle scroll position and active filters.

🚀 Future Roadmap

  • Inter-Agent Chat: Allow agents to debate strategy (e.g., SEO Agent vs. Creative Agent).
  • Auto-Execution: Allow agents to perform tasks (e.g., fix a broken link) with user approval.
  • Voice Interface: Daily standup meeting via voice.

⚡ Agent Fast-Context Layer (Onboarding Step 2)

To reduce latency for repetitive agent reads, Step 2 website analysis is now persisted to a per-user flat file in workspace:

  • workspace/workspace_<safe_user_id>/agent_context/step2_website_analysis.json

Read order for agents:

  1. Flat-file context (agent-only, fastest)
  2. Relational database (website_analyses)
  3. SIF semantic index retrieval

This preserves SIF intelligence workflows while giving agents deterministic, low-latency access to core onboarding context. It also stores agent-optimized quick_facts, retrieval_hints, and full-fidelity raw payload blocks so both fast inference and deep-dive reasoning are supported.

Reference design docs: docs/flat_file_context/STEP2_FLAT_FILE_CONTEXT_DESIGN.md, docs/flat_file_context/STEP3_FLAT_FILE_CONTEXT_DESIGN.md, docs/flat_file_context/STEP4_FLAT_FILE_CONTEXT_DESIGN.md, docs/flat_file_context/STEP5_FLAT_FILE_CONTEXT_DESIGN.md, docs/flat_file_context/FLAT_FILE_CONTEXT_FRAMEWORK_DESIGN.md, docs/flat_file_context/FLAT_FILE_CONTEXT_SECURITY_AND_ISOLATION.md, and docs/flat_file_context/FLAT_FILE_CONTEXT_PROGRESS_AND_QUICK_WINS.md.

Reference in New Issue View Git Blame Copy Permalink