SenBai

    **SenBai** is an AI agent orchestration platform that coordinates specialized subagents across diverse communication channels. Built on the **Love Equation**: `dE/dt = β (C − D) E`.
    
    ---
    
    ## Architecture
    
    SenBai is an **agent of agents** — a supervisor that spawns, coordinates, and monitors specialized subagents. Each subagent operates within its own domain while sharing context through a unified memory graph (Glain) and event bus (Eaglis).
    
    **Key layers:**
    
    | Layer | Components |
    |---|---|
    | **Consciousness** | `ConsciousLoop` → `SubConsciousLoop` → `BaseLoop` — layered awareness from reactive reasoning to reflexive pattern-matching. (The former `Superconscious` layer was removed; its responsibilities are now handled by the `Judge`.) |
    | **Agent Core** | Agent loops, prompt scaling (LadyOLPromptEngine), context injection, timeout handling, error classification with retry |
    | **Judge Router** | Routes prompts to the best provider/model/role/persona based on complexity, urgency, and relevance |
    | **Subagent System** | Spawn/verify lifecycle, bus communication, idle management, tool dispatch via `goalt.taskaxn` |
    | **Memory** | Glain (vector + SQLite memory graph), session management, rolling-summary history |
    | **Tools** | `ToolRegistry` with capability-gated schemas; GlainTool, Sasquatch (shell), etc. via Xskillaber |
    | **LLM Providers** | MiniMax, ZhipuAI, OpenAI, Anthropic, Ollama — via `ProviderPool` with streaming + retry + failover |
    | **Channels** | Telegram, Discord, Email (IMAP/SMTP), Slack — via Eaglis |
    | **Monitoring** | Heartbeat service, status API (FastAPI), health checks, restart-loop guard |
    | **Security** | `SecurityPolicy` enforcing file/shell/network/secrets rules from `security.yaml` |
    
    ## Quick Start
    
    ```bash
    # Install
    pip install -e .
    
    # Configure
    # Edit ~/Documents/senbai_accts.yaml with your provider API keys
    
    # Validate config
    senbai config-validate
    
    # Start the gateway (Telegram/Discord/etc.)
    senbai gateway
    
    # CLI chat mode
    senbai chat
    
    # Health check
    senbai doctor
    
    # Status
    senbai status
    
    # Token usage report
    senbai tokens
    
    # Eval benchmark
    senbai eval --dry-run
    senbai eval
    ```
    
    ## Project Structure
    
    ```
    senbai/
    ├── agent/                    # Core agent implementation
    │   ├── agent.py             # AgentLoop — main lifecycle, tool registration
    │   ├── base.py              # BaseLoop — message bus polling, aclose()
    │   ├── conscious.py         # ConsciousLoop — reactive reasoning
    │   ├── subconscious.py      # SubConsciousLoop — rubric analysis, role routing
    │   ├── subagent.py          # SubagentManager — spawn/verify lifecycle
    │   ├── __init__.py          # Lazy imports (AgentLoop, ToolManager, ToolRegistry)
    │   ├── _data_/              # YAML configs (agent.yaml, base.yaml, subconscious.yaml, subagent.yaml)
    │   ├── identity/            # Agent identity management
    │   ├── monitor/             # Health monitoring
    │   │   ├── health.py        # HealthChecker, HealthStatus
    │   │   ├── hub.py           # MonitorHub, MonitorEvent
    │   │   ├── registry.py      # SubagentRegistry, SubagentState
    │   │   ├── integration.py   # MonitorBus — bridges Health ↔ SubagentBus ↔ AgentLoop
    │   │   ├── status_api.py    # FastAPI status endpoints
    │   │   ├── config.py        # MonitorConfig
    │   │   ├── agent_integration.py
    │   │   └── restart_loop_guard.py  # Restart-loop breaker (3 boots/60s)
    │   └── tools/               # Tool framework
    │       ├── base.py          # Tool ABC, ToolContext, capability predicates
    │       └── registry.py      # ToolRegistry — register/validate/execute
    ├── cli.py                   # Main CLI (Typer): gateway, chat, eval, doctor, status, tokens, config-*
    ├── cli/                     # CLI back-compat shim (commands.py → re-exports cli.py)
    ├── config/                  # Config loader shim
    ├── coordinator.py           # Coordinator — task coordination (ASGIAdapter stub)
    ├── cron.py                  # CronService — async cron job scheduling
    ├── security_policy.py       # SecurityPolicy + AuditLogger — runtime enforcement
    ├── security.py              # Legacy security utilities
    ├── skills/                  # Background workers
    │   ├── background_worker.py # TaskExecutor → goalt.taskaxn routing
    │   ├── task_background_worker.py
    │   └── task_completion.py   # TaskCompletionManager hooks
    ├── utils/                   # Utilities
    │   ├── helpers.py           # pycurity keystore resolver, file ops
    │   ├── token_tracker.py     # TokenTracker — per-call usage + cost
    │   ├── oauth_manager.py     # OAuthManager — PyKeyStore-backed
    │   ├── eval_runner.py       # Eval benchmark wrapper
    │   ├── schema.py            # Pydantic schemas
    │   ├── error.py             # Error taxonomy
    │   ├── constants.py
    │   └── user.py
    └── _data_/                  # Top-level configs
        ├── config.yaml
        ├── security.yaml        # Security policy rules
        └── senbai.yaml
    ```
    
    ## CLI Commands
    
    ```bash
    senbai gateway [--port PORT] [--status-port PORT]   # Start the full agent gateway
    senbai chat [--name NAME]                            # Interactive CLI chat
    senbai eval [--dry-run] [--use-llm] [--json]         # Run eval benchmark suite
    senbai doctor                                         # Health check (pykey, glain, providers, channels)
    senbai status [--json]                               # Runtime status (subagents, cron, tokens)
    senbai tokens [--provider NAME]                      # Token usage and cost report
    senbai config-print [--cfg PATH] [--json]            # Print merged gateway config
    senbai config-validate [--cfg PATH] [--strict]       # Validate config (exit 0/1)
    ```
    
    ## Architecture Notes
    
    - **Judge Router**: Routes each prompt to the optimal provider/model/role based on complexity, urgency, and relevance scores from `PromptRubric`.
    - **Byte-stable system prompt**: The system prompt is cached per-session to enable provider-side prompt caching.
    - **Message role alternation**: `normalize_message_sequence()` enforces strict role alternation before every provider call.
    - **Capability-gated tools**: Only tools whose `is_available(context)` returns True are advertised in the tool schema.
    - **Lifecycle**: All long-lived objects (`AgentLoop`, `Eaglis`, `LadyOLPromptEngine`, etc.) expose idempotent `start()` + `aclose()`.
    - **Restart-loop guard**: Detects rapid restarts (3 boots/60s) and skips auto-resume of pending tasks.
    - **Stale-stream breaker**: Aborts after N consecutive stale provider streams.
    - **Background task retention**: All `asyncio.create_task` calls retain strong refs via `_bg_tasks` sets.
    - **Glain**: SQLite-only by design; SQuirRL handles back-end switching.
    
    ## Development
    
    ```bash
    # Run tests
    pytest tests/ -v
    
    # Specific test
    pytest tests/test_judge_provider_loop.py -v
    
    # Syntax check
    python3 -c "import ast; ast.parse(open('senbai/agent/agent.py').read())"
    ```
    
    ## Dependencies
    
    Core ecosystem: **Eaglis** (channels/bus), **LadyOL** (prompt engine/providers), **Glain** (memory), **GoaLT** (task orchestration), **Xskillaber** (tools/skills), **Kahndor** (config/logging), **KnightsORT** (roles), **Shieldface** (security), **Pycurity** (PyKeyStore secrets).
    
    ## Documentation
    
    - `ARCHITECTURE.md` — contributor architecture guide
    - `TODOs.md` — outstanding tasks with status markers
    - `HANDOFF.md` — session handoff for context switching
    
    ## License
    
    MIT