hyperagents 1.2.3rc5.post3__tar.gz

hyperagents-1.2.3rc5.post3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hypernimbus, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hyperagents-1.2.3rc5.post3/MANIFEST.in

@@ -0,0 +1,7 @@
+prune tests
+prune dist
+prune dist-*
+prune build
+prune .venv
+prune .git
+global-exclude *.pyc __pycache__ .env .env.* *.pem *.key

hyperagents-1.2.3rc5.post3/PKG-INFO

@@ -0,0 +1,469 @@
+Metadata-Version: 2.4
+Name: hyperagents
+Version: 1.2.3rc5.post3
+Summary: Unlimited-domain multi-agent AI swarm platform
+License: MIT
+Project-URL: Homepage, https://gitlab.com/hyper-nimbus-group/hyperclaw
+Project-URL: Repository, https://gitlab.com/hyper-nimbus-group/hyperclaw
+Project-URL: Issues, https://gitlab.com/hyper-nimbus-group/hyperclaw/-/issues
+Project-URL: Changelog, https://gitlab.com/hyper-nimbus-group/hyperclaw/-/blob/main/CHANGELOG.md
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.6
+Requires-Dist: asyncpg>=0.29
+Requires-Dist: pgvector>=0.2
+Requires-Dist: httpx>=0.27
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13.0
+Requires-Dist: textual>=0.61
+Requires-Dist: anthropic>=0.28
+Requires-Dist: openai>=1.30
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: fastapi>=0.109
+Requires-Dist: uvicorn[standard]>=0.27
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: aiofiles>=23.0
+Requires-Dist: python-telegram-bot>=20.0
+Requires-Dist: feedparser>=6.0
+Requires-Dist: apscheduler>=3.10
+Requires-Dist: psutil>=5.9
+Requires-Dist: cryptography>=42
+Requires-Dist: pypdf>=4.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Dynamic: license-file
+
+# HyperClaw
+
+**Your personal AI that actually gets things done.**
+
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/downloads/)
+[![PyPI](https://img.shields.io/pypi/v/hyperagents)](https://pypi.org/project/hyperagents/)
+
+HyperClaw is a personal AI assistant that works across your entire life. Not just chat — it connects to your email, calendar, tasks, documents, and more. It remembers everything, learns your preferences, and coordinates 44 specialized AI agents to help you with anything.
+
+---
+
+## What's New in v0.2.0
+
+- **Claude 5 family** with tiered model routing (sonnet-5 / opus-5 / fable-5) and
+  **automatic failover** — overloads degrade gracefully instead of going silent
+- **Universal file delivery** — the `send_file` tool pushes any document, deck,
+  spreadsheet, image, or video into the conversation you're already in (Telegram
+  documents, iMessage attachments, email attachments) or opens it on the Mac
+- **Full email suite** — HTML email, in-thread replies, forwarding with attachments,
+  drafts-as-approval, archive/star/read, Gmail search
+- **Offsite heartbeat** — a dead-man's-switch template that alerts you externally if
+  the machine running your assistant dies (see `.env.example` → `HEARTBEAT_URL`)
+- **Persona templating** — your assistant's identity lives in an untracked file
+  (`persona.example.md`), not in source code
+- **Hardened channel security** — fail-closed allowlists for iMessage and Telegram;
+  see [SECURITY.md](SECURITY.md) before exposing the bot to any channel
+
+---
+
+## What Can It Do?
+
+- **Manage your communications** — Email, Telegram, Slack, Discord, WhatsApp, Teams
+- **Organize your work** — Calendar, tasks, projects, documents
+- **Handle your data** — Notion, Airtable, Google Sheets, Salesforce, HubSpot
+- **Support your business** — Invoicing, customer tracking, sales pipelines
+- **Research anything** — Web search, document analysis, data synthesis
+- **Remember everything** — Your preferences, history, context across all sessions
+- **Optimize costs** — Smart model routing uses cheap models for simple tasks
+
+One AI. Every platform. All working together.
+
+---
+
+## Architecture
+
+### Cost-Optimized Model Router
+
+HyperClaw intelligently routes tasks to the most cost-effective model:
+
+| Model | Use Case | Cost (input/output per 1k tokens) |
+|-------|----------|------|
+| **ChatJimmy** (Llama 3.1 8B) | Simple queries, classification, quick lookups | ~$0.00001 |
+| **Claude Haiku 4.5** | Moderate tasks, basic analysis | $0.001 / $0.005 |
+| **Claude Sonnet 5** | Everyday requests, drafting, quick answers | $0.002 / $0.010 |
+| **Claude Opus 5** | Analysis, planning, writing, research | $0.005 / $0.025 |
+| **Claude Fable 5** | Hardest multi-step work: code, architecture, quant | $0.010 / $0.050 |
+
+Simple "what time is it?" stays cheap. "Refactor this system end to end" gets Fable 5 — and if a
+model is overloaded, the failover chain walks down the ladder instead of dropping your request.
+
+### Multi-Agent Coordination
+
+44 specialized agents organized by domain:
+
+- **Business (11):** Strategos, Herald, Pipeline, Ledger, Counsel, Talent, Nexus, Ops, Revenue, Sovereign, Venture
+- **Personal (6):** Atlas, Midas, Vitals, Nourish, Navigator, Hearth
+- **Scientific (5):** Medicus, Cosmos, Gaia, Oracle, Scribe
+- **Communications (5):** Echo, Envoy, Pulse, Cipher, Herald
+- **Talent (4):** Scout, Deal, Stage, Roster
+- **Trading (3):** Prediction Strategist, Polymarket Trader, Global Prediction Engine
+- **Technology (3):** Aegis, Bridge, Forge
+- **Recursive (3):** Scout, Alchemist, Calibrator
+- **Intelligence (2):** Sentinel, Arbiter
+- **Creative (2):** Author, Lens
+
+Tasks are automatically routed to the best agent based on domain and complexity.
+
+### Persistent Memory
+
+Memory persists across sessions:
+
+- **Working Memory** — Current context and active tasks
+- **Episodic Memory** — Conversation history and decisions
+- **Semantic Memory** — Facts and knowledge
+- **Instincts** — Learned behavioral patterns
+
+---
+
+## Getting Started
+
+### Option 1: Quick Start (5 minutes)
+
+**macOS:**
+```bash
+brew install pipx
+pipx install hyperagents       # the command is still `hyperclaw`
+hyperclaw init
+```
+
+**Linux/Windows:**
+```bash
+pip install hyperagents
+hyperclaw init
+```
+
+The `init` command runs an interactive setup that will:
+1. Ask for your name and what to call your AI
+2. Guide you through API key setup (Anthropic)
+3. Optionally set up database for persistent memory
+4. Launch the chat interface
+
+Then use interactive chat:
+```bash
+hyperclaw start
+```
+
+Or run the TUI:
+```bash
+hyperclaw-tui
+```
+
+### Option 2: Self-Host with Docker
+
+```bash
+# Clone the repo
+git clone https://gitlab.com/hyper-nimbus-group/hyperclaw.git
+cd hyperclaw
+
+# Copy the example config
+cp .env.example .env
+
+# Edit .env and add your Anthropic API key
+# ANTHROPIC_API_KEY=sk-ant-your-key
+
+# Optional: Add ChatJimmy for cheap simple tasks
+# CHATJIMMY_API_KEY=your-taalas-key
+
+# Start
+docker-compose up
+```
+
+Open `http://localhost:8001` in your browser.
+
+### Option 3: Production Setup
+
+```bash
+# Clone and setup
+git clone https://gitlab.com/hyper-nimbus-group/hyperclaw.git
+cd hyperclaw
+pip install -r requirements.txt
+
+# Initialize workspace and config
+python -m hyperclaw setup
+
+# Initialize database (requires DATABASE_URL in .env)
+python -m hyperclaw setup --init-db
+
+# Start server
+python -m hyperclaw server --port 8001
+```
+
+---
+
+## Configuration
+
+### Required
+- **ANTHROPIC_API_KEY** — Powers the AI brain
+  - Get one at [console.anthropic.com](https://console.anthropic.com)
+
+### Recommended
+- **DATABASE_URL** — PostgreSQL with pgvector for memory
+  - Easiest: [Supabase](https://supabase.com) (free tier works)
+  - Run `schema/init.sql` to create tables
+
+- **CHATJIMMY_API_KEY** — Cheap model for simple tasks
+  - Get one at [taalas.ai](https://taalas.ai)
+  - Reduces costs by 90%+ for simple queries
+
+### Optional Integrations
+
+**Messaging:**
+```bash
+TELEGRAM_BOT_TOKEN=your-bot-token
+SLACK_BOT_TOKEN=xoxb-your-token
+```
+
+Telegram polling and the scheduled jobs (heartbeat, morning brief, nightly
+memory consolidation) are **off by default**. They start only with
+`HYPERCLAW_UNATTENDED=1`; see [docs/UNATTENDED-MODE.md](docs/UNATTENDED-MODE.md).
+
+**Email:**
+```bash
+GMAIL_CLIENT_ID=...
+GMAIL_CLIENT_SECRET=...
+GMAIL_REFRESH_TOKEN=...
+```
+
+See [.env.example](.env.example) for all available integrations.
+
+---
+
+## API Endpoints
+
+### Chat
+```bash
+# Simple chat
+curl -X POST http://localhost:8001/chat \
+  -H "Content-Type: application/json" \
+  -d '{"message": "What can you help me with?"}'
+
+# Streaming chat
+curl -X POST http://localhost:8001/chat/stream \
+  -H "Content-Type: application/json" \
+  -d '{"message": "Explain quantum computing", "stream": true}'
+```
+
+### Tasks
+```bash
+# Create a task
+curl -X POST http://localhost:8001/api/tasks \
+  -H "Content-Type: application/json" \
+  -d '{"goal": "Research competitors in AI space", "domain": "business"}'
+
+# Get task status
+curl http://localhost:8001/api/tasks/abc123
+
+# List all tasks
+curl http://localhost:8001/api/tasks
+```
+
+### Multi-Agent Coordination
+```bash
+# Coordinate complex goal across multiple agents
+curl -X POST http://localhost:8001/api/coordinate \
+  -H "Content-Type: application/json" \
+  -d '{"goal": "Create a complete marketing strategy for product launch"}'
+```
+
+### Memory
+```bash
+# Store a memory
+curl -X POST http://localhost:8001/api/memory/remember \
+  -H "Content-Type: application/json" \
+  -d '{"content": "User prefers concise responses", "importance": 0.8}'
+
+# Recall memories
+curl -X POST http://localhost:8001/api/memory/recall \
+  -H "Content-Type: application/json" \
+  -d '{"query": "user preferences"}'
+```
+
+### Cost Management
+```bash
+# Get current costs
+curl http://localhost:8001/api/costs
+
+# Set daily budget
+curl -X POST "http://localhost:8001/api/costs/budget?budget_usd=5.0"
+
+# List available models
+curl http://localhost:8001/api/models
+```
+
+### System
+```bash
+# Health check
+curl http://localhost:8001/health
+
+# Full status
+curl http://localhost:8001/status
+
+# List agents
+curl http://localhost:8001/api/agents
+
+# List integrations
+curl http://localhost:8001/api/integrations
+```
+
+---
+
+## CLI Commands
+
+```bash
+# Setup workspace and configuration
+hyperclaw setup
+hyperclaw setup --init-db  # Also initialize database
+
+# Start the server
+hyperclaw server
+hyperclaw server --port 8080
+
+# Interactive chat
+hyperclaw chat
+
+# Check status
+hyperclaw status
+
+# Memory operations
+hyperclaw memory list
+hyperclaw memory recall "user preferences"
+hyperclaw memory remember "Important note"
+
+# Version
+hyperclaw version
+```
+
+---
+
+## Workspace Structure
+
+After setup, HyperClaw creates:
+
+```
+~/.hyperclaw/
+├── workspace/
+│   ├── SOUL.md           # AI personality
+│   ├── IDENTITY.md       # AI configuration
+│   ├── USER.md           # Your profile
+│   ├── MEMORY.md         # Working memory
+│   └── secrets/
+│       └── .env          # API keys
+├── memory/
+│   ├── instincts.md      # Learned behaviors
+│   ├── core-episodes.md  # Key memories
+│   └── daily/            # Daily logs
+├── config/
+│   └── hyperclaw.yaml    # System config
+└── logs/
+```
+
+Edit these files to customize your assistant's behavior.
+
+---
+
+## Cost Optimization Tips
+
+1. **Use ChatJimmy** — Add `CHATJIMMY_API_KEY` to route simple tasks to a model that costs 100x less
+
+2. **Cost caps** — every model call goes through the cost guard (`hyperclaw/cost_guard.py`).
+   At the daily cap or the per-task cap HyperClaw **stops** (no further model calls, never a
+   cheaper model) and asks you whether to continue, with what was done (from the activity
+   log and tool results), what remains and the spend so far. Answers above a small amount end
+   with a spend line. Scheduled jobs and guest chats stop and notify you only.
+   - `hyperclaw cost` shows today's spend; `hyperclaw cost raise --daily 20` / `--task 5`
+     (or `/cost raise daily 20` in the terminal) changes a cap — your explicit action,
+     recorded in `hyperclaw activity`.
+   - Settings: `config.json` key `cost_guard` (`daily_cap_usd`, default 10; `task_cap_usd`,
+     default 2; `spend_line_min_usd`, default 0.01; `prices`), else the environment
+     (`HYPERCLAW_DAILY_CAP_USD` — legacy `DAILY_BUDGET_USD` — `HYPERCLAW_TASK_CAP_USD`,
+     `HYPERCLAW_SPEND_LINE_MIN_USD`). Hyper deployments set them in `config.json`.
+   - Prices are USD per 1k tokens: `cost_guard.prices` (`{"<model>" or "provider:<name>":
+     {"input_per_1k": …, "output_per_1k": …}}`), then `models.yaml` `cost_per_1k_*`, then a
+     built-in table. HyperSpeed V2 uses a placeholder rate until Hyper sets its internal rate
+     as `prices["provider:hyperspeed"]`. An unknown model is charged a conservative rate,
+     never 0. Spend is kept per day in `$HYPERCLAW_ROOT/ledger/cost.sqlite3` (survives restarts).
+
+3. **Enable prefer_cheap** — Set `PREFER_CHEAP_MODELS=true` to always prefer the cheapest capable model
+
+4. **Monitor usage** — Check `/api/costs` to see spend by model
+
+---
+
+## Database Setup (Optional but Recommended)
+
+For persistent memory across sessions, set up PostgreSQL with pgvector:
+
+1. Create a Supabase project (free) or use any PostgreSQL
+2. Enable the `vector` extension
+3. Run `schema/init.sql` to create tables
+4. Add `DATABASE_URL` to your `.env`
+
+```bash
+# Initialize database
+python -m hyperclaw setup --init-db
+```
+
+---
+
+## Privacy & Security
+
+- **Your data stays yours** — Self-host means nothing leaves your machine
+- **No tracking** — We don't collect anything
+- **Open source** — Audit the code yourself
+- **Per-agent permissions** — Control what each agent can access
+- **Channel allowlists** — iMessage/Telegram deny strangers by default; read [SECURITY.md](SECURITY.md) before connecting any channel
+
+---
+
+## Troubleshooting
+
+For terminal authentication errors after a Hyperspeed outage, see
+[provider recovery](docs/terminal-provider-recovery.md).
+
+**"API key not working"**
+- Make sure it starts with `sk-ant-`
+- Check for extra spaces when pasting
+
+**"Database connection failed"**
+- Verify your DATABASE_URL is correct
+- For Supabase, use the "Transaction pooler" connection string
+
+**"Integration not connecting"**
+- Run `hyperclaw integrations test <name>` to diagnose
+- Check that API keys are in your `.env` file
+
+**Need help?**
+- Run `hyperclaw status` to check system health
+- Open an issue on [GitLab](https://gitlab.com/hyper-nimbus-group/hyperclaw/-/issues)
+
+---
+
+## Contributing
+
+MIT licensed. Contributions welcome.
+
+```bash
+git clone https://gitlab.com/hyper-nimbus-group/hyperclaw.git
+cd hyperclaw
+pip install -e ".[dev]"
+python -m pytest tests/ -v
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+---
+
+## License
+
+MIT — use it, modify it, build on it.