lulabell-engine 0.3.0__tar.gz

lulabell_engine-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeff Draper
+
+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.

lulabell_engine-0.3.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md
+include LICENSE
+include config.template.yaml
+recursive-include tethr_engine *.py
+recursive-exclude * __pycache__
+recursive-exclude * *.pyc

lulabell_engine-0.3.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: lulabell-engine
+Version: 0.3.0
+Summary: Local-first behavioral intelligence engine with collectors, AI agent, and task executor
+Author: Jeff Draper
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: uvicorn[standard]>=0.20.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-jose[cryptography]>=3.3.0
+Requires-Dist: passlib[bcrypt]>=1.7.4
+Requires-Dist: bcrypt>=4.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: pillow>=9.0.0
+Requires-Dist: sentence-transformers>=2.2.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: groq
+Requires-Dist: anthropic
+Requires-Dist: watchdog
+Requires-Dist: mcp
+Requires-Dist: pywin32>=305; sys_platform == "win32"
+Provides-Extra: ml
+Requires-Dist: scikit-learn; extra == "ml"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# tethr-engine
+
+[![PyPI](https://img.shields.io/pypi/v/tethr-engine)](https://pypi.org/project/tethr-engine)
+[![Python](https://img.shields.io/pypi/pyversions/tethr-engine)](https://pypi.org/project/tethr-engine)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+TETHR is a local-first behavioral intelligence engine.
+It passively observes your devices, detects behavioral
+patterns without cloud processing, and serves real-time
+presence context to AI agents in under 300 tokens.
+
+```bash
+pip install tethr-engine
+tethr start
+```
+
+---
+
+## What it does
+
+- **Passive observation** — watches active windows, typing cadence, system state via background POTS process
+- **Pattern detection** — identifies focus areas, app clusters, work rhythms from local data only
+- **Agent-ready API** — `/identity/context` returns a compact behavioral summary, ready to inject into any system prompt
+- **MCP server** — native Claude Desktop integration via `python -m tethr_engine.mcp_server`
+- **Zero cloud** — everything stays on your device; Groq API used only for LLM inference calls
+
+---
+
+## Quick start
+
+```bash
+pip install tethr-engine
+tethr start          # first run prompts for Groq API key, then serves on :8001
+tethr status         # confirm health
+curl http://127.0.0.1:8001/identity/context
+```
+
+Full walkthrough → [docs/quickstart.md](docs/quickstart.md)
+
+---
+
+## Agent integration
+
+```python
+import requests
+
+context = requests.get("http://127.0.0.1:8001/identity/context", timeout=3).json()["context"]
+system_prompt = f"{your_base_prompt}\n\n[User context]\n{context}"
+```
+
+Query once per session, inject into system prompt. ~200–300 tokens.
+
+Full guide → [docs/integration.md](docs/integration.md)
+
+---
+
+## CLI
+
+| Command | Description |
+|---|---|
+| `tethr start` | Start server on `localhost:8001` |
+| `tethr start --host 0.0.0.0` | Network accessible |
+| `tethr start --reload` | Dev mode |
+| `tethr status` | Health check |
+| `tethr version` | Print version |
+
+---
+
+## Configuring data storage
+
+By default TETHR stores data in the package directory. To use an external drive set `data_path` in `config.yaml`:
+
+```yaml
+data_path: D:\tethr-data
+```
+
+Or set it during first-run setup when prompted. TETHR creates the directory if it does not exist.
+
+---
+
+## Links
+
+- [PyPI](https://pypi.org/project/tethr-engine)
+- [Quickstart](docs/quickstart.md)
+- [Integration guide](docs/integration.md)

lulabell_engine-0.3.0/README.md

@@ -0,0 +1,85 @@
+# tethr-engine
+
+[![PyPI](https://img.shields.io/pypi/v/tethr-engine)](https://pypi.org/project/tethr-engine)
+[![Python](https://img.shields.io/pypi/pyversions/tethr-engine)](https://pypi.org/project/tethr-engine)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+TETHR is a local-first behavioral intelligence engine.
+It passively observes your devices, detects behavioral
+patterns without cloud processing, and serves real-time
+presence context to AI agents in under 300 tokens.
+
+```bash
+pip install tethr-engine
+tethr start
+```
+
+---
+
+## What it does
+
+- **Passive observation** — watches active windows, typing cadence, system state via background POTS process
+- **Pattern detection** — identifies focus areas, app clusters, work rhythms from local data only
+- **Agent-ready API** — `/identity/context` returns a compact behavioral summary, ready to inject into any system prompt
+- **MCP server** — native Claude Desktop integration via `python -m tethr_engine.mcp_server`
+- **Zero cloud** — everything stays on your device; Groq API used only for LLM inference calls
+
+---
+
+## Quick start
+
+```bash
+pip install tethr-engine
+tethr start          # first run prompts for Groq API key, then serves on :8001
+tethr status         # confirm health
+curl http://127.0.0.1:8001/identity/context
+```
+
+Full walkthrough → [docs/quickstart.md](docs/quickstart.md)
+
+---
+
+## Agent integration
+
+```python
+import requests
+
+context = requests.get("http://127.0.0.1:8001/identity/context", timeout=3).json()["context"]
+system_prompt = f"{your_base_prompt}\n\n[User context]\n{context}"
+```
+
+Query once per session, inject into system prompt. ~200–300 tokens.
+
+Full guide → [docs/integration.md](docs/integration.md)
+
+---
+
+## CLI
+
+| Command | Description |
+|---|---|
+| `tethr start` | Start server on `localhost:8001` |
+| `tethr start --host 0.0.0.0` | Network accessible |
+| `tethr start --reload` | Dev mode |
+| `tethr status` | Health check |
+| `tethr version` | Print version |
+
+---
+
+## Configuring data storage
+
+By default TETHR stores data in the package directory. To use an external drive set `data_path` in `config.yaml`:
+
+```yaml
+data_path: D:\tethr-data
+```
+
+Or set it during first-run setup when prompted. TETHR creates the directory if it does not exist.
+
+---
+
+## Links
+
+- [PyPI](https://pypi.org/project/tethr-engine)
+- [Quickstart](docs/quickstart.md)
+- [Integration guide](docs/integration.md)

lulabell_engine-0.3.0/config.template.yaml

@@ -0,0 +1,51 @@
+# TETHR Engine Configuration Template
+# Copy this to data/config.yaml and fill in your values.
+# config.yaml is gitignored — never commit your actual secrets.
+
+# === REQUIRED ===
+data_path: "D:\\TETHR Data"              # Where to store database + files
+user_id: ""                               # Populated automatically during setup
+
+# === AUTHENTICATION ===
+username: ""                              # Your login username
+port: 8001                                # Server port
+
+# === API KEYS (Optional - enables features) ===
+groq_api_key: ""                          # For LLM - get from console.groq.com
+tavily_api_key: ""                        # For web search - get from app.tavily.com
+telegram_token: ""                        # For Telegram - get from @BotFather
+telegram_chat_id: ""                      # Your Telegram chat ID (message @userinfobot)
+
+# === AGENT CONFIG ===
+agent_name: ""                            # Your agent's name (set during onboarding)
+agent_hatched: false                      # Set to true after first conversation
+
+# === DEVICE ===
+device_id: ""                             # This device's hostname (auto-set)
+
+# === OPTIONAL INTEGRATIONS ===
+# zepp_token: ""                          # Amazfit/Zepp API
+# spotify_token: ""                       # Spotify API
+
+# === PROACTIVE ===
+proactive:
+  enabled: true
+  schedule:
+    work_days: [mon, tue, wed, thu, fri]
+    work_start: "08:00"
+    work_end:   "17:00"
+    wake_time_work: "07:00"
+    wake_time_off:  "09:00"
+  quiet_hours:
+    start: 22
+    end: 7
+
+# === SEARCH ===
+search:
+  provider: "tavily"
+  tavily_api_key: ""                      # Can also go in the top-level tavily_api_key
+
+# === STORAGE ===
+storage:
+  photos_path: "D:\\TETHR Photos"
+  inbox_dir:   "inbox"

lulabell_engine-0.3.0/lulabell_engine/__init__.py

@@ -0,0 +1,2 @@
+"""lulabell_engine — Standalone identity engine package."""
+from lulabell_engine.pots_manager import start_pots, stop_pots, is_running

lulabell_engine-0.3.0/lulabell_engine/actioncore/__init__.py

@@ -0,0 +1,2 @@
+"""ActionCore — Task Execution Agent."""
+__version__ = "0.1.0"

lulabell_engine-0.3.0/lulabell_engine/actioncore/api.py

@@ -0,0 +1,269 @@
+"""
+api.py — FastAPI server for ActionCore (port 8002).
+
+Endpoints:
+  GET  /health          — liveness check
+  GET  /status          — queue status + recent task history
+  GET  /tools           — list available tools
+  POST /task            — submit a task {type, params}
+  POST /task/plan       — plan a task (returns steps, no execution)
+  POST /task/execute    — execute a pre-built plan
+  POST /task/run        — plan + execute in one call
+  GET  /task/{id}/status — status of a specific task by id
+  POST /diagnose        — run full system diagnosis
+"""
+import logging
+from typing import Any
+
+from fastapi import FastAPI, HTTPException, Request
+from pydantic import BaseModel
+
+logger = logging.getLogger(__name__)
+
+app = FastAPI(title="ActionCore", version="0.2.0")
+# app.state.core is set by cli.py before the server starts
+
+# ── Valid task types ──────────────────────────────────────────────────────────
+
+_VALID_TYPES = {
+    "email_send",
+    "file_store",
+    "file_retrieve",
+    "system_status",
+    "llm_query",
+    "run_plan",
+    "diagnose_tethr",
+    "fix_collector",
+    "update_tethr",
+    "self_repair",
+}
+
+
+# ── Request models ────────────────────────────────────────────────────────────
+
+class TaskRequest(BaseModel):
+    type:   str
+    params: dict[str, Any] = {}
+
+
+class PlanRequest(BaseModel):
+    description: str
+    stop_on_failure: bool = True
+
+
+class StepDict(BaseModel):
+    action:          str
+    tool:            str
+    params:          dict[str, Any] = {}
+    expected_result: str = ""
+    stop_on_failure: bool = True
+
+
+class ExecuteRequest(BaseModel):
+    description: str = ""
+    steps:       list[StepDict]
+    stop_on_failure: bool = True
+
+
+class RunRequest(BaseModel):
+    description:     str
+    stop_on_failure: bool = True
+    plan_only:       bool = False
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def _get_core(request: Request):
+    core = request.app.state.core
+    if core is None:
+        raise HTTPException(503, "Core not initialised")
+    return core
+
+
+# ── Endpoints ─────────────────────────────────────────────────────────────────
+
+@app.get("/health")
+def health():
+    cfg  = getattr(app.state, "config", {})
+    name = cfg.get("agent_name", "ActionCore")
+    return {"status": "ok", "agent": name, "version": "0.2.0"}
+
+
+@app.get("/status")
+def get_status(request: Request):
+    return _get_core(request).queue.get_status()
+
+
+@app.get("/tools")
+def list_tools():
+    """Return the list of available tools and their capabilities."""
+    return {
+        "tools": [
+            {
+                "name":  "bash",
+                "desc":  "Execute shell commands",
+                "params": ["command", "timeout", "allow_dangerous"],
+            },
+            {
+                "name":  "files",
+                "desc":  "Read, write, and edit files (within ALLOWED_PATHS)",
+                "params": ["action", "path", "content", "old_text", "new_text"],
+            },
+            {
+                "name":  "docker",
+                "desc":  "Manage Docker containers and compose stacks",
+                "params": ["action", "container", "image", "compose_file"],
+            },
+            {
+                "name":  "systemd",
+                "desc":  "Control system services (Linux systemctl / Windows sc)",
+                "params": ["action", "name"],
+            },
+            {
+                "name":  "git",
+                "desc":  "Git repository operations",
+                "params": ["action", "repo_path", "branch"],
+            },
+            {
+                "name":  "config",
+                "desc":  "Read/write YAML and JSON config files",
+                "params": ["action", "path", "key", "value"],
+            },
+            {
+                "name":  "logs",
+                "desc":  "Inspect log files",
+                "params": ["action", "path", "lines", "search"],
+            },
+            {
+                "name":  "diagnose",
+                "desc":  "System health diagnostics",
+                "params": ["check"],
+                "checks": ["tethr_health", "collectors", "disk", "memory", "ports", "processes", "full"],
+            },
+        ]
+    }
+
+
+@app.post("/task")
+def submit_task(req: TaskRequest, request: Request):
+    """Submit a background task to the ActionCore queue."""
+    core = _get_core(request)
+
+    if req.type not in _VALID_TYPES:
+        raise HTTPException(
+            400,
+            f"Unknown task type {req.type!r}. Valid: {sorted(_VALID_TYPES)}",
+        )
+
+    task = core.queue.submit(req.type, req.params)
+    logger.info("[api] task submitted id=%s type=%s", task.id, task.type)
+    return {"task_id": task.id, "status": task.status, "type": task.type}
+
+
+@app.post("/task/plan")
+def plan_task(req: PlanRequest):
+    """
+    Plan a task and return the ordered steps — does NOT execute.
+    Use POST /task/run to plan + execute.
+    """
+    try:
+        from lulabell_engine.actioncore.planner import plan_task as _plan
+        steps = _plan(req.description)
+        return {
+            "description": req.description,
+            "steps":       [s.to_dict() for s in steps],
+            "step_count":  len(steps),
+        }
+    except Exception as exc:
+        raise HTTPException(500, str(exc))
+
+
+@app.post("/task/execute")
+def execute_plan(req: ExecuteRequest):
+    """Execute a pre-built list of steps (from /task/plan or hand-crafted)."""
+    try:
+        from lulabell_engine.actioncore.planner  import Step
+        from lulabell_engine.actioncore.executor import execute_plan as _exec
+        from lulabell_engine.actioncore.validator import validate_task
+
+        steps  = [Step.from_dict(s.dict()) for s in req.steps]
+        result = _exec(steps, task_description=req.description,
+                       stop_on_failure=req.stop_on_failure)
+        val    = validate_task(req.description, result)
+
+        return {
+            **result.to_dict(),
+            "validation": val.to_dict(),
+        }
+    except Exception as exc:
+        raise HTTPException(500, str(exc))
+
+
+@app.post("/task/run")
+def run_task(req: RunRequest):
+    """Plan and execute a task description in one call."""
+    try:
+        from lulabell_engine.actioncore.planner   import plan_task as _plan
+        from lulabell_engine.actioncore.executor  import execute_plan as _exec
+        from lulabell_engine.actioncore.validator import validate_task
+
+        steps = _plan(req.description)
+
+        if req.plan_only:
+            return {
+                "description": req.description,
+                "steps":       [s.to_dict() for s in steps],
+                "step_count":  len(steps),
+                "executed":    False,
+            }
+
+        result = _exec(steps, task_description=req.description,
+                       stop_on_failure=req.stop_on_failure)
+        val    = validate_task(req.description, result)
+
+        return {
+            **result.to_dict(),
+            "validation": val.to_dict(),
+            "executed":   True,
+        }
+    except Exception as exc:
+        raise HTTPException(500, str(exc))
+
+
+@app.get("/task/{task_id}/status")
+def task_status(task_id: str, request: Request):
+    """Get the current status of a queued/completed task by id."""
+    core = _get_core(request)
+    for task in core.queue._history:
+        if task.id == task_id:
+            return task.to_dict()
+    # Check if it's still in the queue (pending)
+    raise HTTPException(404, f"Task {task_id!r} not found")
+
+
+@app.post("/diagnose")
+def diagnose():
+    """Run a full system diagnosis and return the report."""
+    try:
+        from lulabell_engine.actioncore.tools.diagnose import full_diagnosis
+        report = full_diagnosis()
+
+        # High-level summary
+        issues = []
+        if not report["tethr"].get("server_up"):
+            issues.append("LulaBell server not responding")
+        silent = report["collectors"].get("silent", [])
+        if silent:
+            issues.append(f"Silent collectors: {', '.join(silent)}")
+        for part in report["disk"].get("low_space", []):
+            issues.append(f"Low disk space: {part}")
+        if report["memory"].get("low_memory"):
+            issues.append(f"High RAM usage: {report['memory']['ram_pct_used']:.0f}%")
+
+        return {
+            "healthy": len(issues) == 0,
+            "issues":  issues,
+            "report":  report,
+        }
+    except Exception as exc:
+        raise HTTPException(500, str(exc))