gulama 0.2.0__tar.gz

gulama-0.2.0/.gitignore

@@ -0,0 +1,71 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+coverage.xml
+
+# Environment & Secrets — NEVER commit these
+.env
+.env.local
+.env.production
+*.age
+*.key
+*.pem
+vault.*
+!.env.example
+
+# Gulama data directory (may exist during dev)
+.gulama/
+
+# OS files
+.DS_Store
+Thumbs.db
+desktop.ini
+nul
+
+# Claude Code
+.claude/
+
+# PDFs (analysis docs, not source code)
+*.pdf
+
+# Docker
+docker-compose.override.yml
+
+# Rust
+target/
+
+# Node (web UI)
+node_modules/
+web/dist/
+
+# Logs
+*.log
+logs/
+
+# Cache
+cache/

gulama-0.2.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to Gulama will be documented in this file.
+
+## [0.2.0] - 2025-02-15
+
+### Added
+- **19 built-in skills**: File Manager, Shell Exec, Web Search, Notes, Code Exec, Browser, Email, Calendar, MCP Bridge, Voice, Image Gen, Smart Home, GitHub, Notion, Spotify, Twitter/X, Google Docs, Productivity (Trello/Linear/Todoist/Obsidian), Self-Modify
+- **8 communication channels**: CLI, Telegram, Discord, Slack, WhatsApp, Matrix (E2E encrypted), Microsoft Teams, Google Chat
+- **GulamaHub marketplace**: Ed25519-signed skill marketplace with search, install, publish
+- **Self-modifying skills**: AI can create/test/register its own skills at runtime with security scanning
+- **Voice wake word**: "Hey Gulama" via Picovoice Porcupine with energy-based fallback
+- **WebSocket debug tools**: Real-time tool call, policy decision, token usage streaming
+- **Docker production deployment**: Multi-stage build, Caddy auto-TLS, Watchtower
+- **Sub-agent manager**: Spawn background agents for parallel tasks
+- **Task scheduler**: Cron, interval, and one-shot task scheduling
+- **29 REST API endpoints**: Full gateway API with TOTP authentication
+- **CI/CD pipeline**: GitHub Actions with lint, test, security scan, Docker build, PyPI publish
+- **Integration tests**: Brain flow, gateway endpoints, skill execution, security pipeline
+
+### Security
+- **15+ security mechanisms**: Policy engine, sandbox, canary tokens, audit, DLP, egress filter, RBAC, SSO, threat detection, input validation, security headers
+- **Signed marketplace**: Ed25519 mandatory verification for all community skills
+- **Self-modifier scanning**: Blocks dangerous code patterns (subprocess, eval, exec, ctypes)
+
+## [0.1.0] - 2025-02-10
+
+### Added
+- Initial release with core agent brain
+- LiteLLM universal LLM support (100+ providers)
+- Encrypted SQLite memory store
+- AES-256-GCM secrets vault
+- Cedar-inspired policy engine
+- bubblewrap sandbox
+- Canary token system
+- Hash-chain audit logger
+- TOTP authentication gateway
+- CLI and Telegram channels
+- 4 core skills: File Manager, Shell Exec, Web Search, Notes

gulama-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Santosh — Astra Fintech Labs Pvt. Ltd.
+
+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.

gulama-0.2.0/PKG-INFO

@@ -0,0 +1,418 @@
+Metadata-Version: 2.4
+Name: gulama
+Version: 0.2.0
+Summary: Secure, open-source personal AI agent platform — OpenClaw, but secure.
+Project-URL: Homepage, https://gulama.ai
+Project-URL: Repository, https://github.com/san-techie21/gulama-bot
+Project-URL: Documentation, https://gulama.dev
+Project-URL: Issues, https://github.com/san-techie21/gulama-bot/issues
+Project-URL: Changelog, https://github.com/san-techie21/gulama-bot/blob/main/CHANGELOG.md
+Author-email: Santosh <santosh@astrafintechlabs.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,automation,chatbot,llm,personal-assistant,security
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: chromadb>=0.6
+Requires-Dist: click>=8.1
+Requires-Dist: cryptography>=44.0
+Requires-Dist: diskcache>=5.6
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.28
+Requires-Dist: keyring>=25.0
+Requires-Dist: litellm>=1.56
+Requires-Dist: pydantic-settings>=2.7
+Requires-Dist: pydantic>=2.10
+Requires-Dist: pyotp>=2.9
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: python-telegram-bot>=22.0
+Requires-Dist: rich>=13.9
+Requires-Dist: sentence-transformers>=3.3
+Requires-Dist: structlog>=24.4
+Requires-Dist: tomli-w>=1.1
+Requires-Dist: tomli>=2.2
+Requires-Dist: uvicorn[standard]>=0.34
+Requires-Dist: websockets>=14.0
+Provides-Extra: all-channels
+Requires-Dist: discord-py>=2.4; extra == 'all-channels'
+Requires-Dist: matrix-nio[e2e]>=0.24; extra == 'all-channels'
+Requires-Dist: playwright>=1.48; extra == 'all-channels'
+Requires-Dist: slack-sdk>=3.33; extra == 'all-channels'
+Provides-Extra: all-skills
+Requires-Dist: caldav>=1.4; extra == 'all-skills'
+Requires-Dist: google-api-python-client>=2.150; extra == 'all-skills'
+Requires-Dist: google-auth>=2.30; extra == 'all-skills'
+Requires-Dist: openai>=1.50; extra == 'all-skills'
+Requires-Dist: playwright>=1.48; extra == 'all-skills'
+Provides-Extra: browser
+Requires-Dist: playwright>=1.48; extra == 'browser'
+Provides-Extra: browser-ai
+Requires-Dist: browser-use>=0.1; extra == 'browser-ai'
+Requires-Dist: langchain-openai>=0.2; extra == 'browser-ai'
+Requires-Dist: playwright>=1.48; extra == 'browser-ai'
+Provides-Extra: calendar
+Requires-Dist: caldav>=1.4; extra == 'calendar'
+Requires-Dist: google-api-python-client>=2.150; extra == 'calendar'
+Provides-Extra: dev
+Requires-Dist: bandit>=1.7; extra == 'dev'
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pip-audit>=2.7; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff<0.16,>=0.15; extra == 'dev'
+Provides-Extra: discord
+Requires-Dist: discord-py>=2.4; extra == 'discord'
+Provides-Extra: email
+Provides-Extra: full
+Requires-Dist: browser-use>=0.1; extra == 'full'
+Requires-Dist: caldav>=1.4; extra == 'full'
+Requires-Dist: discord-py>=2.4; extra == 'full'
+Requires-Dist: google-api-python-client>=2.150; extra == 'full'
+Requires-Dist: google-auth>=2.30; extra == 'full'
+Requires-Dist: langchain-openai>=0.2; extra == 'full'
+Requires-Dist: matrix-nio[e2e]>=0.24; extra == 'full'
+Requires-Dist: openai>=1.50; extra == 'full'
+Requires-Dist: playwright>=1.48; extra == 'full'
+Requires-Dist: slack-sdk>=3.33; extra == 'full'
+Provides-Extra: google-workspace
+Requires-Dist: google-api-python-client>=2.150; extra == 'google-workspace'
+Requires-Dist: google-auth>=2.30; extra == 'google-workspace'
+Provides-Extra: image
+Requires-Dist: openai>=1.50; extra == 'image'
+Provides-Extra: matrix
+Requires-Dist: matrix-nio[e2e]>=0.24; extra == 'matrix'
+Provides-Extra: rust
+Requires-Dist: maturin>=1.7; extra == 'rust'
+Provides-Extra: saml
+Requires-Dist: python3-saml>=1.16; extra == 'saml'
+Provides-Extra: slack
+Requires-Dist: slack-sdk>=3.33; extra == 'slack'
+Provides-Extra: teams
+Requires-Dist: botbuilder-core>=4.15; extra == 'teams'
+Provides-Extra: voice
+Requires-Dist: elevenlabs>=1.0; extra == 'voice'
+Requires-Dist: gtts>=2.5; extra == 'voice'
+Requires-Dist: openai-whisper>=20240930; extra == 'voice'
+Provides-Extra: voice-wake
+Requires-Dist: pvporcupine>=3.0; extra == 'voice-wake'
+Requires-Dist: pyaudio>=0.2; extra == 'voice-wake'
+Provides-Extra: whatsapp
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="media/Gulama.png" alt="Gulama" width="200"/>
+</p>
+
+<h1 align="center">Gulama</h1>
+
+<p align="center">
+  <strong>Secure, open-source personal AI agent platform — OpenClaw, but secure.</strong>
+</p>
+
+<p align="center">
+  Gulama is a security-first AI assistant with <b>19 skills</b>, <b>8 channels</b>, a <b>signed skill marketplace</b>, and support for <b>100+ LLM providers</b>. Runs on macOS, Windows, Linux, Docker, and ARM.
+</p>
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"/></a>
+  <a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.12+-green.svg" alt="Python 3.12+"/></a>
+  <a href="https://github.com/san-techie21/gulama-bot/actions"><img src="https://github.com/san-techie21/gulama-bot/actions/workflows/ci.yml/badge.svg" alt="CI"/></a>
+  <a href="https://pypi.org/project/gulama/"><img src="https://img.shields.io/pypi/v/gulama.svg" alt="PyPI"/></a>
+  <img src="https://img.shields.io/badge/Security-15%2B%20mechanisms-red.svg" alt="Security"/>
+</p>
+
+## Why Gulama?
+
+Personal AI agents handle sensitive data — your files, emails, credentials, and conversations. Most existing solutions (including OpenClaw with its [341 malicious skills](https://www.securityweek.com/openclaw-vulnerabilities/)) treat security as an afterthought. **Gulama is built security-first from the ground up.**
+
+### Security Architecture (15+ Mechanisms)
+
+- **Encrypted at rest** — AES-256-GCM for all credentials, never plaintext
+- **Sandboxed execution** — bubblewrap/Docker/OS sandbox for every tool
+- **Policy engine** — Deterministic Cedar-inspired authorization
+- **Canary tokens** — Real-time prompt injection detection
+- **Tamper-proof audit logs** — Hash-chain audit trail
+- **Egress filtering + DLP** — Prevents data exfiltration and credential leaks
+- **Signed skills (GulamaHub)** — Ed25519 verification prevents supply-chain attacks
+- **TOTP authentication** — Time-based one-time passwords for API access
+- **Rate limiting** — Per-IP request throttling
+- **Input validation** — Content scanning and sanitization
+- **Loopback binding** — Gateway binds 127.0.0.1 only (never 0.0.0.0 without explicit flag)
+- **Threat detection** — Brute force, privilege escalation, anomaly detection
+- **RBAC** — Role-based access control with team management
+- **SSO/API keys** — OIDC, SAML, API key authentication
+- **Security headers** — HSTS, CSP, X-Frame-Options, and more
+
+## Quick Start
+
+### One-Line Install
+
+```bash
+pip install gulama
+```
+
+### With All Features
+
+```bash
+pip install gulama[full]
+```
+
+### Setup
+
+```bash
+gulama setup
+```
+
+The setup wizard walks you through:
+1. Creating a master password (encrypts all credentials)
+2. Choosing your LLM provider and entering your API key
+3. Setting your autonomy level
+4. Optional channel configuration
+
+### Run
+
+```bash
+# Interactive CLI chat
+gulama chat
+
+# Start the gateway server (REST API + WebSocket)
+gulama start
+
+# Start with specific channel
+gulama start --channel telegram
+gulama start --channel discord
+gulama start --channel matrix
+
+# Start with always-on voice
+gulama start --voice-wake
+
+# Security health check
+gulama doctor
+```
+
+### Docker
+
+```bash
+# Standard deployment
+docker compose up -d
+
+# With Redis + ChromaDB
+docker compose --profile full up -d
+
+# Cloud deployment (auto-TLS via Caddy)
+docker compose -f docker-compose.yml -f docker-compose.cloud.yml up -d
+```
+
+## 19 Built-In Skills
+
+| Skill | Description | API/Service |
+|-------|-------------|-------------|
+| **File Manager** | Read, write, search files | Local filesystem |
+| **Shell Exec** | Execute commands in sandbox | OS shell |
+| **Web Search** | Search and fetch web pages | DuckDuckGo/SearXNG |
+| **Notes** | Save/recall facts and preferences | Local memory |
+| **Code Exec** | Run Python/JS/Bash snippets | Sandboxed runtime |
+| **Browser** | Navigate, screenshot, AI browsing | Playwright + browser-use |
+| **Email** | Read, compose, send emails | IMAP/SMTP |
+| **Calendar** | Manage events and schedules | Google Calendar/CalDAV |
+| **MCP Bridge** | Connect to MCP servers | Model Context Protocol |
+| **Voice** | Speech-to-text and text-to-speech | Whisper/Deepgram/ElevenLabs |
+| **Image Gen** | Generate images from text | DALL-E/Stability AI/Replicate |
+| **Smart Home** | Control IoT devices | Home Assistant |
+| **GitHub** | Repos, issues, PRs, code search | GitHub API |
+| **Notion** | Pages, databases, search | Notion API |
+| **Spotify** | Playback, search, playlists | Spotify Web API |
+| **Twitter/X** | Tweet search, user info | Twitter API v2 |
+| **Google Docs** | Docs, Sheets, Drive | Google Workspace APIs |
+| **Productivity** | Trello, Linear, Todoist, Obsidian | Multi-service |
+| **Self-Modify** | AI writes its own new skills | Runtime skill authoring |
+
+## 8 Communication Channels
+
+| Channel | Status | Protocol |
+|---------|--------|----------|
+| **CLI** | Ready | Interactive terminal |
+| **Telegram** | Ready | Bot API |
+| **Discord** | Ready | discord.py |
+| **Slack** | Ready | Slack SDK + Webhooks |
+| **WhatsApp** | Ready | Cloud API |
+| **Matrix** | Ready | matrix-nio (E2E encrypted) |
+| **Microsoft Teams** | Ready | Bot Framework webhooks |
+| **Google Chat** | Ready | Workspace webhooks |
+
+Plus: **Web UI** channel and **Voice Wake** (always-on "Hey Gulama" listener).
+
+## Universal LLM Support
+
+Works with **any** LLM provider via LiteLLM:
+
+| Provider | Models |
+|----------|--------|
+| Anthropic | Claude Sonnet 4.5, Opus 4.6, Haiku 4.5 |
+| OpenAI | GPT-4o, o1, o3-mini |
+| Google | Gemini 2.0 Flash, Pro |
+| DeepSeek | DeepSeek Chat, Reasoner |
+| Alibaba | Qwen Plus, Max, Turbo |
+| Groq | Llama 3.3, Mixtral |
+| Ollama | Any local model |
+| Together AI | Llama, Mistral, and more |
+| AWS Bedrock | All Bedrock models |
+| Azure OpenAI | All Azure models |
+| 90+ more | Any OpenAI-compatible endpoint |
+
+## GulamaHub — Secure Skill Marketplace
+
+Unlike other agent platforms, **every community skill must be Ed25519-signed**. No exceptions.
+
+```bash
+# Search skills
+gulama hub search "weather"
+
+# Install (signature verified automatically)
+gulama hub install weather-checker
+
+# Publish your own (signing required)
+gulama hub publish my-skill --sign
+```
+
+The agent can also **write its own skills** at runtime via the Self-Modify skill — with full sandboxing and security scanning.
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                     Channels (8)                          │
+│  CLI │ Telegram │ Discord │ Slack │ WhatsApp │ Matrix    │
+│  Teams │ Google Chat │ Web UI │ Voice Wake              │
+├──────────────────────────────────────────────────────────┤
+│              Gateway (FastAPI) — 29 Routes                │
+│  TOTP Auth │ Rate Limit │ CORS │ Security Headers        │
+├──────────────────────────────────────────────────────────┤
+│                  Agent Brain                              │
+│  Context Builder (RAG) │ LLM Router │ Tool Calling Loop  │
+│  Sub-Agent Manager │ Task Scheduler                      │
+├──────────────────────────────────────────────────────────┤
+│                 Security Layer (15+)                      │
+│ Policy Engine │ Sandbox │ Canary │ Audit │ DLP │ Egress  │
+│ RBAC │ SSO │ Threat Detection │ Input Validation         │
+├──────────────────────────────────────────────────────────┤
+│              Skills (19 Built-in + Marketplace)           │
+│ Files │ Shell │ Web │ Browser │ Email │ Calendar │ Voice │
+│ GitHub │ Notion │ Spotify │ Google Docs │ Self-Modify    │
+├──────────────────────────────────────────────────────────┤
+│                   Storage Layer                           │
+│  Encrypted SQLite │ ChromaDB (RAG) │ Secrets Vault       │
+│  Hash-Chain Audit │ Disk Cache                           │
+├──────────────────────────────────────────────────────────┤
+│                   Debug & Monitoring                      │
+│  WebSocket Debug Stream │ Cost Tracking │ Token Budgets  │
+└──────────────────────────────────────────────────────────┘
+```
+
+## REST API (29 Endpoints)
+
+| Endpoint | Description |
+|----------|-------------|
+| `POST /api/v1/chat` | Send message to agent |
+| `GET /api/v1/status` | Agent status and stats |
+| `GET /api/v1/skills` | List all registered skills |
+| `GET /api/v1/agents` | List background sub-agents |
+| `POST /api/v1/agents/spawn` | Spawn background agent |
+| `GET /api/v1/scheduler/tasks` | List scheduled tasks |
+| `GET /api/v1/hub/search` | Search skill marketplace |
+| `GET /api/v1/conversations` | List conversations |
+| `GET /api/v1/audit` | View audit log |
+| `GET /api/v1/cost/today` | Token usage and cost |
+| `GET /api/v1/debug/events` | Debug event stream |
+| `ws://localhost:18789/ws/chat` | Real-time WebSocket chat |
+| `ws://localhost:18789/ws/debug` | Live debug inspector |
+
+## Autonomy Levels
+
+| Level | Name | Behavior |
+|-------|------|----------|
+| 0 | Observer | Ask before every action |
+| 1 | Assistant | Auto-read, ask before writes |
+| 2 | Co-pilot | Auto safe actions, ask before shell/network |
+| 3 | Autopilot-cautious | Auto most things, ask before destructive |
+| 4 | Autopilot | Auto everything except financial/credential |
+
+## Development
+
+```bash
+# Clone
+git clone https://github.com/san-techie21/gulama-bot.git
+cd gulama-bot
+
+# Setup dev environment
+pip install -e ".[dev]"
+
+# Run tests (209 tests)
+python -m pytest tests/ -v
+
+# Security health check
+gulama doctor --json-output
+
+# Lint
+ruff check src/
+```
+
+## Configuration
+
+Configuration is loaded from:
+1. `config/default.toml` (secure defaults)
+2. `~/.gulama/config.toml` (user overrides)
+3. Environment variables (`GULAMA_*`)
+4. `.env` file (for secrets — see `.env.example`)
+
+Key security defaults (cannot be disabled without `--i-know-what-im-doing`):
+- Gateway binds to `127.0.0.1` only
+- Sandbox enabled
+- Policy engine enabled
+- Audit logging enabled
+- Skill signatures required
+
+## Deployment
+
+| Method | Command | Use Case |
+|--------|---------|----------|
+| **pip install** | `pip install gulama` | Local development |
+| **Docker** | `docker compose up -d` | Self-hosted server |
+| **Cloud** | `docker compose -f ... up -d` | DigitalOcean/AWS/GCP |
+| **Docker + TLS** | With `docker-compose.cloud.yml` | Production with auto-HTTPS |
+
+## vs OpenClaw
+
+| Feature | Gulama | OpenClaw |
+|---------|--------|----------|
+| Security mechanisms | 15+ | ~0 |
+| Memory encryption | AES-256-GCM | None |
+| Skill signing | Ed25519 mandatory | None (341 malicious skills found) |
+| LLM providers | 100+ (LiteLLM) | ~5 |
+| Policy engine | Cedar-inspired | None |
+| Sandbox | bubblewrap/Docker | Container-only |
+| Audit trail | Hash-chain | Basic logs |
+| Cost controls | Per-day budgets | None |
+| Self-modifying skills | Yes (sandboxed) | No |
+| License | MIT | MIT |
+
+## License
+
+MIT License. See [LICENSE](LICENSE).
+
+## Security
+
+Found a vulnerability? Please report it responsibly via [GitHub Issues](https://github.com/san-techie21/gulama-bot/issues) with the `security` label.
+
+---
+
+**Built with security as the #1 priority by [Astra Fintech Labs](https://astrafintechlabs.com).**