solvent-agent 0.1.0__py3-none-any.whl

solvent/__init__.py

@@ -0,0 +1,3 @@
+"""SOLVENT — a self-funding analyst agent. See run_demo.py."""
+
+__version__ = "0.1.0"

solvent/__main__.py

@@ -0,0 +1,172 @@
+"""SOLVENT CLI entry point: python3 -m solvent.
+
+Commands: [serve|worker|telegram|doctor|pairing|...]
+"""
+
+import sys
+
+from . import __version__
+
+HELP = """\
+SOLVENT — a self-funding analyst agent.
+
+Usage: solvent <command> [options]
+       solvent                 run the demo (interactive onboarding on first run)
+
+Commands:
+  (none)        run the batch demo / interactive session
+  init          first-run setup: create dirs, DB, and workspace files
+  status        live summary: balance, jobs, API key presence; --watch to auto-refresh
+  upgrade       check for newer version on PyPI; --check exits 1 if outdated
+  jobs          list/show/retry/cancel jobs (jobs --help for sub-commands)
+  logs          tail the structured event log; -f to follow, --job/--stage to filter
+  config        show/get/set/reset local configuration values
+  serve         webhooks + job API + hosted briefs
+  worker        resume incomplete jobs, process the queue
+  telegram      long-poll the Telegram bot
+  finance       income statement, unit economics, runway, forecast (alias: report)
+  reconcile     Stripe <-> ledger drift check
+  doctor        stack diagnostics
+  pairing       manage Telegram DM pairing codes
+  workspace     seed the agent workspace (SOUL/BRAIN/AGENTS)
+  retry <id>    re-run a stuck job
+  webhooks      inspect the webhook event log (stats|list|failed)
+  help          show this message
+  version       print the installed version
+
+Run `solvent <command> --help` where supported for command-specific options.
+"""
+
+
+def _print_version() -> None:
+    print(f"solvent {__version__}")
+
+
+def main() -> None:
+    if len(sys.argv) > 1 and sys.argv[1] in ("version", "--version", "-V"):
+        _print_version()
+        return
+    if len(sys.argv) > 1 and sys.argv[1] in ("help", "--help", "-h"):
+        print(HELP)
+        return
+    if len(sys.argv) > 1 and sys.argv[1] == "init":
+        sys.argv.pop(1)
+        from .init import main as init_main
+
+        init_main()
+    elif len(sys.argv) > 1 and sys.argv[1] == "status":
+        sys.argv.pop(1)
+        from .status import main as status_main
+
+        status_main()
+    elif len(sys.argv) > 1 and sys.argv[1] == "jobs":
+        sys.argv.pop(1)
+        from .job_cmd import main as jobs_main
+
+        jobs_main()
+    elif len(sys.argv) > 1 and sys.argv[1] == "upgrade":
+        sys.argv.pop(1)
+        from .upgrade import main as upgrade_main
+
+        upgrade_main()
+    elif len(sys.argv) > 1 and sys.argv[1] == "logs":
+        sys.argv.pop(1)
+        from .logs import main as logs_main
+
+        logs_main()
+    elif len(sys.argv) > 1 and sys.argv[1] == "config":
+        sys.argv.pop(1)
+        from .config_cmd import main as config_main
+
+        config_main()
+    elif len(sys.argv) > 1 and sys.argv[1] == "serve":
+        sys.argv.pop(1)
+        from .server import main as serve_main
+
+        serve_main()
+    elif len(sys.argv) > 1 and sys.argv[1] == "worker":
+        sys.argv.pop(1)
+        from .worker import main as worker_main
+
+        worker_main()
+    elif len(sys.argv) > 1 and sys.argv[1] == "reconcile":
+        sys.argv.pop(1)
+        from .reconcile import main as reconcile_main
+
+        reconcile_main()
+    elif len(sys.argv) > 1 and sys.argv[1] == "doctor":
+        sys.argv.pop(1)
+        from .doctor import main as doctor_main
+
+        doctor_main()
+    elif len(sys.argv) > 1 and sys.argv[1] == "telegram":
+        sys.argv.pop(1)
+        from .channels.telegram import main as telegram_main
+
+        telegram_main()
+    elif len(sys.argv) > 1 and sys.argv[1] == "pairing":
+        sys.argv.pop(1)
+        from .pairing import main as pairing_main
+
+        pairing_main()
+    elif len(sys.argv) > 1 and sys.argv[1] == "workspace":
+        sys.argv.pop(1)
+        from .workspace import main as workspace_main
+
+        workspace_main()
+    elif len(sys.argv) > 1 and sys.argv[1] == "retry":
+        job_id = sys.argv[2] if len(sys.argv) > 2 else None
+        if not job_id:
+            print("Usage: python -m solvent retry <job_id>")
+            sys.exit(1)
+        from .guardrails import Guardrails
+        from .stages import StageRunner
+        from .stripe_client import StripeClient
+        from .treasury import Treasury
+
+        t = Treasury()
+        s = StageRunner(treasury=t, guard=Guardrails(t), stripe=StripeClient())
+        result = s.retry_job(job_id)
+        import json
+
+        print(json.dumps(result, indent=2, default=str))
+    elif len(sys.argv) > 1 and sys.argv[1] in ("finance", "report"):
+        sys.argv.pop(1)
+        from .finance import main as finance_main
+
+        finance_main()
+    elif len(sys.argv) > 1 and sys.argv[1] == "webhooks":
+        import json
+
+        from .webhook_log import WebhookLog
+
+        wl = WebhookLog()
+        sub = sys.argv[2] if len(sys.argv) > 2 else "stats"
+        if sub == "stats":
+            print(json.dumps(wl.stats(), indent=2))
+        elif sub == "list":
+            for row in wl.list_recent(20):
+                print(
+                    f"{row['received_at_fmt']} [{row['status']}] {row['event_type']} "
+                    f"{row['event_id'][:16]}"
+                )
+        elif sub == "failed":
+            for row in wl.list_failed():
+                print(f"  {row['event_id'][:16]} {row['event_type']} err={row['error'][:60]}")
+    else:
+        # No subcommand: fall through to the demo / interactive CLI.
+        # Update checks are opt-in only (SOLVENT_UPDATE_CHECK=1) — run
+        # `solvent upgrade` explicitly to check for a newer version.
+        import os
+
+        if os.environ.get("SOLVENT_UPDATE_CHECK", "").strip() in ("1", "true", "yes"):
+            from .upgrade import background_update_hint
+
+            background_update_hint()
+        from .cli import main as demo_main
+
+        demo_main()
+
+
+if __name__ == "__main__":
+    main()

solvent/agent.py

@@ -0,0 +1,90 @@
+"""
+agent.py — the SOLVENT orchestrator.
+
+For each inbound job the agent runs an idempotent stage machine:
+  1. QUOTES through the margin gate
+  2. EARNS via Stripe Checkout (webhook-first; sync confirm in demo mode)
+  3. FULFILS via bounded Nemotron tool-calling
+  4. DELIVERS hosted brief + optional email
+  5. SPENDS on vendors (guardrail-screened)
+  6. BOOKS P&L into the treasury
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from collections.abc import Callable
+
+from .guardrails import Guardrails
+from .pricing import PricingPolicy
+from .stages import StageRunner, validate_and_coerce_job
+from .stripe_client import StripeClient
+from .treasury import Treasury
+
+
+class Solvent:
+    def __init__(
+        self,
+        seed_cents: int = 10_000,
+        fresh: bool = True,
+        on_event: Callable | None = None,
+        *,
+        sync_payment: bool | None = None,
+    ):
+        self.t = Treasury()
+        if fresh:
+            self.t.reset()
+            self.t.seed(seed_cents)
+        self.guard = Guardrails(self.t)
+        self.stripe = StripeClient()
+        self.pricing = PricingPolicy()
+        self.log: list[dict] = []
+        self.on_event = on_event
+        if sync_payment is None:
+            async_flag = os.environ.get("SOLVENT_ASYNC", "").strip()
+            sync_payment = async_flag not in ("1", "true", "yes")
+        self._runner = StageRunner(
+            self.t,
+            self.guard,
+            self.stripe,
+            self.pricing,
+            on_event=self._capture_event,
+            sync_payment=sync_payment,
+        )
+
+    def _capture_event(self, event: dict):
+        self.log.append(event)
+        if self.on_event:
+            self.on_event(event)
+
+    def _emit(self, **event):
+        if "ts" not in event:
+            event["ts"] = time.time()
+        self.log.append(event)
+        if self.on_event:
+            self.on_event(event)
+        return event
+
+    def handle_job(self, job: dict) -> dict:
+        return self._runner.run_job(job)
+
+    def advance_job(self, job_id: str) -> dict:
+        return self._runner.advance_job(job_id)
+
+    def enqueue_job(self, job: dict) -> dict:
+        """Validate and persist a job for async worker processing."""
+        validated, err = validate_and_coerce_job(job, self.t)
+        if err:
+            job_id = validated.get("id", "unknown") if validated else "unknown"
+            return self._emit(stage="declined", job_id=job_id, reason=err)
+        assert validated is not None
+        q = self._runner._stage_quote(validated)
+        if q.get("stage") == "declined" or not q.get("accept"):
+            return q
+        return self._runner._stage_checkout(validated, q)
+
+    def run(self, jobs: list[dict]) -> dict:
+        for job in jobs:
+            self.handle_job(job)
+        return self.t.snapshot()

solvent/channels/__init__.py

@@ -0,0 +1 @@
+"""Channel adapters (OpenClaw-style)."""

solvent/channels/telegram.py

@@ -0,0 +1,104 @@
+"""Telegram channel adapter (OpenClaw long-poll pattern)."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import urllib.request
+from typing import TYPE_CHECKING
+
+from ..gateway import Gateway, register_outbound
+
+if TYPE_CHECKING:  # pragma: no cover - typing-only imports
+    from telegram import Update
+    from telegram.ext import ContextTypes
+
+
+def send_telegram_message(external_id: str, text: str) -> None:
+    """Sync outbound via Telegram HTTP API (safe from worker threads)."""
+    token = os.environ.get("TELEGRAM_BOT_TOKEN", "").strip()
+    if not token:
+        return
+    url = f"https://api.telegram.org/bot{token}/sendMessage"
+    payload = json.dumps({"chat_id": int(external_id), "text": text[:4000]}).encode()
+    headers = {"Content-Type": "application/json"}
+    req = urllib.request.Request(url, data=payload, headers=headers)
+    try:
+        urllib.request.urlopen(req, timeout=15)
+    except Exception as exc:
+        logging.getLogger(__name__).warning("telegram send failed: %s", exc)
+
+
+def _require_ptb():
+    """Import the runtime symbols we need from python-telegram-bot.
+
+    ``Update``/``ContextTypes`` are only needed for annotations, so they are
+    imported under ``TYPE_CHECKING`` instead of being returned here.
+    """
+    try:
+        from telegram.ext import (
+            Application,
+            CommandHandler,
+            MessageHandler,
+            filters,
+        )
+
+        return (
+            Application,
+            CommandHandler,
+            MessageHandler,
+            filters,
+        )
+    except ImportError as exc:
+        raise RuntimeError(
+            'python-telegram-bot required. Install: pip install -e ".[telegram]"'
+        ) from exc
+
+
+async def _reply(update: Update, text: str) -> None:
+    if update.message:
+        await update.message.reply_text(text[:4000])
+
+
+def build_application(gateway: Gateway | None = None) -> object:
+    (
+        Application,
+        CommandHandler,
+        MessageHandler,
+        filters,
+    ) = _require_ptb()
+    token = os.environ.get("TELEGRAM_BOT_TOKEN", "").strip()
+    if not token:
+        raise RuntimeError("TELEGRAM_BOT_TOKEN not set")
+
+    gw = gateway or Gateway()
+    register_outbound("telegram", send_telegram_message)
+
+    async def on_message(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        if not update.message or not update.effective_user:
+            return
+        user = update.effective_user
+        text = update.message.text or ""
+        username = user.username
+        reply = gw.handle_inbound("telegram", str(user.id), text, user_label=username)
+        await _reply(update, reply)
+
+    app = Application.builder().token(token).build()
+    app.add_handler(CommandHandler("start", on_message))
+    app.add_handler(CommandHandler("help", on_message))
+    app.add_handler(CommandHandler("status", on_message))
+    app.add_handler(CommandHandler("jobs", on_message))
+    app.add_handler(CommandHandler("quote", on_message))
+    app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, on_message))
+    return app
+
+
+def main():
+    app = build_application()
+    print("SOLVENT Telegram bot starting (long-poll)...")
+    app.run_polling(allowed_updates=["message"])
+
+
+if __name__ == "__main__":
+    main()

solvent/chat.py

@@ -0,0 +1,279 @@
+"""Conversational harness + business tools for gateway channels."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import uuid
+
+from . import nemotron, tools
+from .agent import Solvent
+from .memory import SessionMemory
+from .pricing import quote
+from .security import InputValidationError, PromptInjectionError, sanitise_prompt_input
+from .treasury import fmt
+from .workspace import build_chat_system_prompt, ensure_workspace
+
+_EMAIL_RE = re.compile(r"[\w.+-]+@[\w.-]+\.\w+")
+_BUDGET_RE = re.compile(
+    r"(?:budget|pay|spend)\s*[:\\$]?\s*\$?(\d+(?:\.\d{1,2})?)",
+    re.IGNORECASE,
+)
+
+
+def _new_chat_job_id(agent: Solvent) -> str:
+    """Generate a server-owned chat job ID that does not overwrite an existing job."""
+    for _ in range(10):
+        job_id = "T" + uuid.uuid4().hex[:8]
+        if not agent.t.get_job(job_id):
+            return job_id
+    return "T" + uuid.uuid4().hex
+
+
+def _make_executor(agent: Solvent, session_id: str, live_search: bool):
+    ctx = tools.ToolContext()
+
+    def run(name: str, args: dict) -> str:
+        if name == "treasury_status":
+            s = agent.t.snapshot()
+            return json.dumps(
+                {
+                    "balance_cents": s["balance_cents"],
+                    "revenue_cents": s["revenue_cents"],
+                    "expense_cents": s["expense_cents"],
+                    "margin_pct": s["margin_pct"],
+                }
+            )
+        if name == "list_jobs":
+            jobs = agent.t.list_jobs_for_session(session_id)[-10:]
+            return json.dumps(
+                [{"id": j["id"], "status": j.get("status"), "topic": j.get("topic")} for j in jobs]
+            )
+        if name == "job_status":
+            jid = args.get("job_id", "")
+            row = agent.t.get_job_for_session(jid, session_id)
+            if not row:
+                return json.dumps({"error": "job not found"})
+            metrics = agent.t.get_metrics(jid)
+            return json.dumps({"job": row, "metrics": metrics})
+        if name == "quote_brief":
+            job = {
+                "id": "Q-preview",
+                "topic": args.get("topic", ""),
+                "budget_cents": int(args.get("budget_cents", 0)),
+                "est_tokens": 8000,
+                "market_data_calls": 2,
+                "web_search_calls": 6,
+            }
+            q = quote(job, agent.pricing)
+            return json.dumps(
+                {
+                    "accept": q.accept,
+                    "price_cents": q.price_cents,
+                    "est_cost_cents": q.est_cost_cents,
+                    "margin_pct": q.margin_pct,
+                    "reason": q.reason,
+                }
+            )
+        if name == "submit_brief":
+            topic = args.get("topic", "")
+            budget = int(args.get("budget_cents", 0))
+            email = args.get("customer_email", "client@example.com")
+            job_id = _new_chat_job_id(agent)
+            job = {
+                "id": job_id,
+                "topic": topic,
+                "budget_cents": budget,
+                "customer_email": email,
+                "est_tokens": 8000,
+                "market_data_calls": 2,
+                "web_search_calls": 6,
+                "context": f"Commissioned via chat session {session_id}",
+                "job_owner_session_id": session_id,
+            }
+            result = agent.enqueue_job(job)
+            if result.get("stage") != "declined" and not result.get("error"):
+                agent.t.update_chat_session(session_id, notify_job_id=job_id, pending_job_json="")
+            if result.get("url"):
+                return json.dumps(
+                    {
+                        "job_id": job_id,
+                        "checkout_url": result.get("url"),
+                        "stage": result.get("stage", "invoice"),
+                    }
+                )
+            return json.dumps(result)
+        if name in tools.ALLOWED_TOOLS:
+            return tools.dispatch(
+                name,
+                args,
+                ctx,
+                lambda s, u: nemotron.complete(s, u)[0],
+                live_search=live_search,
+            )
+        return json.dumps({"error": f"unknown tool {name!r}"})
+
+    return run
+
+
+def _load_pending(agent: Solvent, session_id: str) -> dict:
+    sess = agent.t.get_chat_session(session_id)
+    if not sess or not sess.get("pending_job_json"):
+        return {}
+    try:
+        return json.loads(sess["pending_job_json"])
+    except json.JSONDecodeError:
+        return {}
+
+
+def _save_pending(agent: Solvent, session_id: str, pending: dict) -> None:
+    agent.t.update_chat_session(session_id, pending_job_json=json.dumps(pending))
+
+
+def _merge_commission_slots(agent: Solvent, session_id: str, text: str) -> dict:
+    """Accumulate topic/budget/email across turns for brief commissioning."""
+    pending = _load_pending(agent, session_id)
+    lower = text.lower()
+    if any(k in lower for k in ("brief", "commission", "research on", "report on")):
+        pending.setdefault("intent", "commission")
+    if "topic" in lower and ":" in text:
+        _, topic = text.split(":", 1)
+        pending["topic"] = topic.strip()[:200]
+    elif pending.get("intent") and len(text) > 10 and "topic" not in pending:
+        pending.setdefault("topic", text.strip()[:200])
+    m = _BUDGET_RE.search(text)
+    if m:
+        pending["budget_cents"] = int(float(m.group(1)) * 100)
+    em = _EMAIL_RE.search(text)
+    if em:
+        pending["customer_email"] = em.group(0)
+    if pending:
+        _save_pending(agent, session_id, pending)
+    return pending
+
+
+def _pending_prompt(pending: dict) -> str:
+    if not pending or pending.get("intent") != "commission":
+        return ""
+    have = []
+    need = []
+    for key, label in (
+        ("topic", "topic"),
+        ("budget_cents", "budget_cents"),
+        ("customer_email", "customer_email"),
+    ):
+        if pending.get(key):
+            have.append(f"{label}={pending[key]}")
+        else:
+            need.append(label)
+    if not need:
+        return (
+            "Pending commission slots are complete: "
+            + ", ".join(have)
+            + ". Confirm with the user before submit_brief."
+        )
+    return (
+        "Pending commission (slot-filling): have "
+        + (", ".join(have) if have else "nothing yet")
+        + f"; still need: {', '.join(need)}."
+    )
+
+
+def handle_message(
+    session_id: str,
+    text: str,
+    *,
+    agent: Solvent | None = None,
+    memory: SessionMemory | None = None,
+    channel: str = "cli",
+) -> str:
+    """Run one conversational turn; returns assistant reply text."""
+    ensure_workspace()
+    agent = agent or Solvent(seed_cents=10_000, fresh=False, sync_payment=False)
+    memory = memory or SessionMemory(agent.t)
+    system_prompt = build_chat_system_prompt(channel)
+
+    try:
+        text = sanitise_prompt_input(text, field_name="message", max_len=4000)
+    except (PromptInjectionError, InputValidationError) as exc:
+        return f"Message rejected: {exc}"
+
+    memory.append(session_id, "user", text)
+    pending = _merge_commission_slots(agent, session_id, text)
+    history = memory.format_for_prompt(session_id, limit=20)
+    live_search = os.environ.get("SOLVENT_LIVE_SEARCH", "").strip() in (
+        "1",
+        "true",
+        "yes",
+    )
+
+    catalog = {**tools.TOOL_REGISTRY, **tools.BUSINESS_TOOL_REGISTRY}
+    executor = _make_executor(agent, session_id, live_search)
+    tool_lines = "\n".join(
+        f"- {name}: {meta.get('description', '')}" for name, meta in catalog.items()
+    )
+
+    slot_hint = _pending_prompt(pending)
+    user = (
+        f"Conversation so far:\n{history}\n\n"
+        f"Available tools: {', '.join(sorted(catalog))}\n"
+        f"{tool_lines}\n"
+    )
+    if slot_hint:
+        user += f"\n{slot_hint}\n"
+    user += f"\nUser: {text}"
+
+    tool_budget = tools.MAX_TOOL_CALLS
+    calls_made = 0
+    for _ in range(6):
+        reply, _ = nemotron.complete(system_prompt, user)
+        calls = nemotron.parse_tool_calls(reply)
+        if not calls:
+            memory.append(session_id, "assistant", reply)
+            return reply
+        notes = []
+        for name, args in calls:
+            if calls_made >= tool_budget:
+                notes.append(
+                    f"[budget] per-turn tool-call limit ({tool_budget}) reached; "
+                    "answer the user now without more tool calls."
+                )
+                break
+            result = executor(name, args)
+            calls_made += 1
+            notes.append(f"[{name}] {result}")
+        user = user + f"\n\nAssistant: {reply}\n\nTool results:\n" + "\n".join(notes)
+
+    fallback = (
+        "I'm having trouble completing that request. "
+        "Try /status or ask for a quote with topic and budget."
+    )
+    memory.append(session_id, "assistant", fallback)
+    return fallback
+
+
+def format_job_notification(event: dict) -> str | None:
+    stage = event.get("stage")
+    jid = event.get("job_id", "")
+    try:
+        from .workspace import append_daily_memory
+
+        if stage in ("paid", "fulfilled", "delivered", "declined"):
+            append_daily_memory(f"job {jid}: {stage}")
+    except Exception as exc:
+        logging.getLogger(__name__).warning("format_job_notification memory append failed: %s", exc)
+    if stage == "paid":
+        return (
+            f"Payment received for job {jid} ({fmt(event.get('amount', 0))}). Fulfillment starting."
+        )
+    if stage == "fulfilled":
+        return f"Job {jid} fulfilled. Report saved."
+    if stage == "delivered":
+        return f"Your brief for {jid} is ready: {event.get('url', '')}"
+    if stage == "declined":
+        return f"Job {jid} declined: {event.get('reason', '')}"
+    if stage == "payment_pending":
+        return f"Awaiting payment for {jid}: {event.get('url', '')}"
+    return None