opusmanSEEKv4/src/nexus_os/monitoring/INTEGRATION.md

================================================================================
TOKENGUARD INTEGRATION GUIDE
================================================================================
Nexus OS v3.0 - Token Monitoring Layer

================================================================================
QUICK START
================================================================================

1. Import TokenGuard:
   from src.nexus_os.monitoring.token_guard import TokenGuard

2. Initialize with budgets:
   guard = TokenGuard(budgets={
       'agent': 50000,
       'skill': 10000,
       'swarm': 200000,
       'session': 500000
   })

3. Track token usage:
   guard.track('foreman-1', 1250, operation='inference')

4. Check budget before operation:
   if guard.check('foreman-1', 5000):
       # Proceed with operation
       pass

5. Atomic reserve:
   result = guard.check_and_reserve('foreman-1', 5000)
   if result['allowed']:
       # Execute operation

================================================================================
INTEGRATION POINTS
================================================================================

BRIDGE (bridge/server.py):
  - Add X-Nexus-Input-Tokens header to responses
  - Track tokens per agent call

GOVERNOR (governor/):
  - Check budget before task delegation
  - Enforce hard stops at 95% threshold
  - Log to VAP audit trail

ENGINE (engine/executor.py):
  - Track tokens per task execution
  - Route to fallback model when budget low
  - Update Mem0 with usage patterns

VAULT (vault/):
  - Store token events in memory layer
  - Query historical usage for SkillSmith
  - Semantic cache for repeated queries

SKILLS (skills/):
  - Track tokens per skill execution
  - Optimize skill manifest based on usage

================================================================================
HOT PATH (Non-Blocking)
================================================================================

Foreman track() call:
  # ~1ms latency
  guard.track(agent_id, tokens)

Bridge response header:
  # No blocking
  X-Nexus-Input-Tokens: 1250
  X-Nexus-Output-Tokens: 890

================================================================================
WARM PATH (Async)
================================================================================

Model routing:
  model = guard.route(task_type='code', complexity='low')
  
Semantic cache check:
  result = guard.semantic_cache_get(query_hash)
  if result:
      return cached_result

================================================================================
COLD PATH (Background)
================================================================================

Trend analysis:
  python -c "
  from src.nexus_os.monitoring.token_guard import TokenGuard
  guard = TokenGuard()
  print(guard.analyze_trends('foreman-1', '24h'))
  "

Budget optimization:
  # SkillSmith reads trends and proposes optimization
  # 8-18% savings per cycle

================================================================================
COUNTERS
================================================================================

Local (ai-tokenizer):
  from src.nexus_os.monitoring.counters import LocalCounter
  counter = LocalCounter()
  count = counter.count("text to count")

Cloud (tokscale):
  from src.nexus_os.monitoring.counters import TokscaleCounter
  counter = TokscaleCounter()
  count = counter.count("text to count")

Native (Ollama/OpenAI):
  from src.nexus_os.monitoring.counters import NativeCounter
  counter = NativeCounter('qwen3:4b-thinking')
  count = counter.count("text to count")

================================================================================
STRATEGIES
================================================================================

Semantic Cache:
  from src.nexus_os.monitoring.strategies import SemanticCache
  cache = SemanticCache(threshold=0.85)
  cache.set(query_hash, response)
  result = cache.get(query_hash)
  print(cache.stats())  # hit rate

Model Router:
  from src.nexus_os.monitoring.strategies import ModelRouter
  router = ModelRouter()
  model = router.route('code', 'low')
  fallback = router.get_fallback('gpt-5.4')

Budget Manager:
  from src.nexus_os.monitoring.strategies import BudgetManager
  manager = BudgetManager(total_budget=500000)
  manager.allocate('agent', 50000)

================================================================================