roscoe 2.0.0__tar.gz → 2.2.0__tar.gz

{roscoe-2.0.0/roscoe.egg-info → roscoe-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roscoe
-Version: 2.0.0
+Version: 2.2.0
 Summary: roscoe — Ready-to-run Orchestration SDK: Configurable, Observable, Extensible.
 Author-email: rhealaloo <rhealaloo@gmail.com>
 License-Expression: MIT

{roscoe-2.0.0 → roscoe-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "roscoe"
-version = "2.0.0"
+version = "2.2.0"
 description = "roscoe — Ready-to-run Orchestration SDK: Configurable, Observable, Extensible."
 readme = "README.md"
 requires-python = ">=3.11"

{roscoe-2.0.0 → roscoe-2.2.0}/roscoe/__init__.py

@@ -3,6 +3,6 @@
 from roscoe.core.agent_result import AgentResult
 from roscoe.core.agent_runner import AgentRunner
 
-__version__ = "2.0.0"
+__version__ = "2.2.0"
 
 __all__ = ["AgentRunner", "AgentResult", "__version__"]

{roscoe-2.0.0 → roscoe-2.2.0}/roscoe/cli/init_command.py

@@ -32,6 +32,7 @@ _PROVIDERS = {
     "azure_openai": {"env_key": "AZURE_OPENAI_KEY", "default_model": "gpt-4o", "base_url": None},
     "anthropic": {"env_key": "ANTHROPIC_API_KEY", "default_model": "claude-sonnet-4-5", "base_url": None},
     "gemini": {"env_key": "GOOGLE_API_KEY", "default_model": "gemini-1.5-pro", "base_url": None},
+    "nvidia": {"env_key": "NVIDIA_API_KEY", "default_model": "openai/gpt-oss-120b", "base_url": None},
     "ollama": {"env_key": None, "default_model": "llama3.1", "base_url": None},
 }
 
@@ -195,6 +196,7 @@ def _run_wizard(name: str) -> dict:
         "azure_openai": "azure_openai",
         "anthropic": "anthropic",
         "gemini": "gemini",
+        "nvidia": "nvidia  (NVIDIA NIM, free-tier models available)",
         "ollama": "ollama  (free, local, no API key)",
     }
     for i, p in enumerate(providers, 1):
@@ -355,10 +357,7 @@ def _apply_wizard(dest: Path, answers: dict) -> None:
         tools_yaml = ", ".join(f'"{t}"' for t in answers["approval_tools"])
         text = text.replace(
             "  # human_approval:\n"
-            "  #   require_approval_for:\n"
-            "  #     - send_email             # tool function names that need sign-off\n"
-            "  #     - delete_record\n"
-            "  #     - submit_payment",
+            "  #   require_approval_for: [send_email, delete_record]   # gate sensitive tools",
             f"  human_approval:\n"
             f"    require_approval_for: [{tools_yaml}]",
         )
@@ -374,7 +373,7 @@ def _apply_wizard(dest: Path, answers: dict) -> None:
 
     if answers["persistent_memory"]:
         text = text.replace(
-            "    enabled: false              # flip to true to enable cross-session memory",
+            "    enabled: false                # long-term facts per user_id",
             "    enabled: true",
         )
 
@@ -416,6 +415,7 @@ def scaffold_project(
 def _add_template_extras(dest: Path, template: str) -> None:
     (dest / "main.py").write_text(_TEMPLATE_MAIN[template])
     (dest / ".env.example").write_text(_TEMPLATE_ENV[template])
+    shutil.copy(SCAFFOLD_DIR / "docs.md", dest / "docs.md")
     evals_dir = dest / "evals"
     evals_dir.mkdir(exist_ok=True)
     (evals_dir / "test_cases.json").write_text(json.dumps(_EXAMPLE_CASES, indent=2))

{roscoe-2.0.0 → roscoe-2.2.0}/roscoe/cli/main.py

@@ -5,9 +5,14 @@ from __future__ import annotations
 import click
 
 # Load .env before any config parsing so ${ENV_VAR} references resolve.
+# usecwd=True: search from the current working directory (the user's project),
+# not from wherever roscoe itself is installed — without it, a non-editable
+# install (e.g. `pip install roscoe`) walks up from inside site-packages and
+# never finds a project's .env file at all.
 try:
+    from dotenv import find_dotenv as _find_dotenv
     from dotenv import load_dotenv as _load_dotenv
-    _load_dotenv()
+    _load_dotenv(_find_dotenv(usecwd=True))
 except ImportError:
     pass
 

{roscoe-2.0.0 → roscoe-2.2.0}/roscoe/cli/run_web.py

@@ -110,7 +110,10 @@ def _result_payload(result: Any, state: dict[str, Any]) -> dict[str, Any]:
                 "tool_calls": action.get("tool_calls", [])}
     if result.status == "error":
         return {"type": "error", "error": str(result.error)}
-    return {"type": "final", "output": result.output,
+    # Some models occasionally stop with an empty final message (no tool_calls,
+    # no content) — never render a literally blank bubble for that.
+    output = result.output or "(no response from the model — try rephrasing)"
+    return {"type": "final", "output": output,
             "tokens": result.total_tokens, "cost": cost, "tools": result.tool_calls}
 
 
@@ -118,105 +121,109 @@ _PAGE = r"""<!DOCTYPE html>
 <html lang="en"><head>
 <meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>roscoe run</title>
+<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
 <style>
   *,*::before,*::after{box-sizing:border-box;margin:0;padding:0}
   body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;
-    background:#0b0d12;color:#e2e8f0;height:100vh;overflow:hidden}
+    background:#f7f8fa;color:#1e293b;height:100vh;overflow:hidden}
 
-  /* landing page behind the widget */
-  .landing{height:100vh;display:flex;align-items:center;justify-content:center;
-    background:radial-gradient(circle at 30% 20%,#182338,#0b0d12 60%)}
-  .card{width:380px;max-width:90vw;background:#161923;border:1px solid #262b38;border-radius:16px;padding:32px}
-  .card h1{font-size:20px;font-weight:700;margin-bottom:6px}
-  .card p{font-size:13px;color:#8b93a3;margin-bottom:24px}
+  /* 12-col split: 3 cols sidebar, 9 cols chat */
+  .layout{display:grid;grid-template-columns:repeat(12,1fr);height:100vh}
+  .sidebar{grid-column:span 3;background:#fff;border-right:1px solid #e2e8f0;
+    padding:32px 24px;display:flex;flex-direction:column}
+  .sidebar h1{font-size:19px;font-weight:700;margin-bottom:6px;color:#0f172a}
+  .sidebar p{font-size:13px;color:#64748b;margin-bottom:24px;line-height:1.5}
   .field{margin-bottom:14px}
-  .field label{display:block;font-size:12px;color:#8b93a3;margin-bottom:6px}
-  .field input{width:100%;padding:10px 13px;background:#0f1117;border:1px solid #334155;
-    border-radius:10px;color:#e2e8f0;font-size:14px;outline:none}
+  .field label{display:block;font-size:12px;color:#64748b;margin-bottom:6px}
+  .field input{width:100%;padding:10px 13px;background:#f8fafc;border:1px solid #cbd5e1;
+    border-radius:10px;color:#0f172a;font-size:14px;outline:none}
   .field input:focus{border-color:#2563eb}
-  .card button{width:100%;margin-top:8px;padding:11px;background:#2563eb;color:#fff;border:none;
+  .sidebar button{width:100%;margin-top:8px;padding:11px;background:#2563eb;color:#fff;border:none;
     border-radius:10px;font-weight:600;font-size:14px;cursor:pointer}
-  .card button:hover{background:#1d4ed8}
-  .signedin{display:none;text-align:center;font-size:13px;color:#8b93a3}
-  .signedin b{color:#e2e8f0}
+  .sidebar button:hover{background:#1d4ed8}
+  .signedin{display:none;font-size:13px;color:#64748b}
+  .signedin b{color:#0f172a}
+  .meta-block{margin-top:auto;padding-top:20px;border-top:1px solid #e2e8f0;font-size:11px;color:#94a3b8}
+  .meta-block div{margin-bottom:4px}
 
-  /* floating launcher */
-  .launcher{position:fixed;right:24px;bottom:24px;width:58px;height:58px;border-radius:50%;
-    background:#2563eb;display:flex;align-items:center;justify-content:center;cursor:pointer;
-    box-shadow:0 6px 20px rgba(37,99,235,.45);z-index:20;transition:transform .15s}
-  .launcher:hover{transform:scale(1.06)}
-  .launcher svg{width:26px;height:26px;fill:#fff}
-  .dot{position:absolute;top:2px;right:2px;width:12px;height:12px;background:#22c55e;border:2px solid #0b0d12;border-radius:50%}
-
-  /* chat panel */
-  .panel{position:fixed;right:24px;bottom:96px;width:360px;height:520px;max-height:76vh;
-    background:#161923;border:1px solid #262b38;border-radius:16px;display:flex;flex-direction:column;
-    overflow:hidden;box-shadow:0 20px 50px rgba(0,0,0,.5);z-index:21;
-    opacity:0;transform:translateY(16px) scale(.98);pointer-events:none;transition:opacity .16s,transform .16s}
-  .panel.open{opacity:1;transform:translateY(0) scale(1);pointer-events:auto}
-  .phead{background:linear-gradient(135deg,#1e3a5f,#0f172a);padding:14px 16px;display:flex;align-items:center;justify-content:space-between}
-  .phead .t{font-size:14px;font-weight:600}
-  .phead .s{font-size:10.5px;opacity:.65;margin-top:1px}
-  .pclose{cursor:pointer;opacity:.7;font-size:18px;line-height:1;padding:2px 4px}
-  .pclose:hover{opacity:1}
-  .msgs{flex:1;overflow-y:auto;padding:14px;display:flex;flex-direction:column;gap:10px}
-  .msgs::-webkit-scrollbar{width:5px}.msgs::-webkit-scrollbar-thumb{background:#334155;border-radius:3px}
-  .m{max-width:84%;padding:9px 13px;border-radius:13px;font-size:13.5px;line-height:1.5;white-space:pre-wrap;word-wrap:break-word}
-  .m.user{align-self:flex-end;background:#2563eb;color:#fff;border-bottom-right-radius:4px}
-  .m.bot{align-self:flex-start;background:#1e2430;color:#e2e8f0;border-bottom-left-radius:4px}
-  .m.err{align-self:center;background:#3b0d0d;color:#f87171;font-size:12.5px}
-  .typing{align-self:flex-start;background:#1e2430;border-radius:13px;border-bottom-left-radius:4px;
-    padding:11px 15px;display:flex;gap:4px}
-  .typing span{width:6px;height:6px;border-radius:50%;background:#64748b;animation:bounce 1.2s infinite}
+  /* chat column */
+  .chat{grid-column:span 9;display:flex;flex-direction:column;min-height:0;background:#fff}
+  .chead{padding:18px 28px;border-bottom:1px solid #e2e8f0;display:flex;align-items:center;justify-content:space-between}
+  .chead .t{font-size:15px;font-weight:600;color:#0f172a}
+  .chead .s{font-size:11px;color:#94a3b8;margin-top:2px}
+  .msgs{flex:1;overflow-y:auto;padding:24px 28px;display:flex;flex-direction:column;gap:12px;background:#f7f8fa}
+  .msgs::-webkit-scrollbar{width:6px}.msgs::-webkit-scrollbar-thumb{background:#cbd5e1;border-radius:3px}
+  .m{max-width:65%;padding:10px 15px;border-radius:14px;font-size:14px;line-height:1.55;word-wrap:break-word}
+  .m.user{align-self:flex-end;background:#2563eb;color:#fff;border-bottom-right-radius:4px;white-space:pre-wrap}
+  .m.bot{align-self:flex-start;background:#fff;color:#1e293b;border:1px solid #e2e8f0;border-bottom-left-radius:4px}
+  .m.err{align-self:center;background:#fef2f2;color:#dc2626;font-size:13px;border:1px solid #fecaca}
+  .m.bot p{margin:0 0 8px}.m.bot p:last-child{margin-bottom:0}
+  .m.bot ul,.m.bot ol{margin:0 0 8px 20px}
+  .m.bot code{background:#f1f5f9;padding:1px 5px;border-radius:4px;font-size:12.5px;font-family:ui-monospace,monospace}
+  .m.bot pre{background:#0f172a;color:#e2e8f0;padding:10px 12px;border-radius:8px;overflow-x:auto;margin:0 0 8px}
+  .m.bot pre code{background:none;padding:0;color:inherit}
+  .m.bot table{border-collapse:collapse;margin:0 0 8px;font-size:13px}
+  .m.bot th,.m.bot td{border:1px solid #e2e8f0;padding:5px 9px;text-align:left}
+  .m.bot th{background:#f8fafc}
+  .m.bot a{color:#2563eb}
+  .typing{align-self:flex-start;background:#fff;border:1px solid #e2e8f0;border-radius:14px;border-bottom-left-radius:4px;
+    padding:12px 16px;display:flex;gap:4px}
+  .typing span{width:6px;height:6px;border-radius:50%;background:#94a3b8;animation:bounce 1.2s infinite}
   .typing span:nth-child(2){animation-delay:.15s}.typing span:nth-child(3){animation-delay:.3s}
   @keyframes bounce{0%,60%,100%{transform:translateY(0);opacity:.5}30%{transform:translateY(-4px);opacity:1}}
-  .approve{align-self:flex-start;background:#3a2e07;border:1px solid #a16207;border-radius:12px;padding:11px 14px;font-size:12.5px}
-  .approve b{color:#fbbf24}.approve .tc{font-family:ui-monospace,monospace;color:#fde68a;margin:5px 0;word-break:break-all}
-  .approve button{border:none;border-radius:8px;padding:6px 14px;font-weight:600;cursor:pointer;margin-right:8px;margin-top:6px;font-size:12px}
+  .approve{align-self:flex-start;background:#fffbeb;border:1px solid #fcd34d;border-radius:12px;padding:12px 15px;font-size:13px;max-width:70%}
+  .approve b{color:#b45309}
+  .approve .tc{margin:8px 0}
+  .approve .tc-name{font-family:ui-monospace,monospace;font-weight:600;color:#92400e;margin-bottom:4px}
+  .approve table.tc-args{border-collapse:collapse;width:100%}
+  .approve .tc-k{font-family:ui-monospace,monospace;color:#92400e;opacity:.75;padding:3px 8px 3px 0;
+    vertical-align:top;white-space:nowrap;font-size:12px}
+  .approve .tc-v{font-family:ui-monospace,monospace;color:#78350f;padding:3px 0;word-break:break-word;font-size:12px}
+  .approve button{border:none;border-radius:8px;padding:7px 15px;font-weight:600;cursor:pointer;margin-right:8px;margin-top:6px;font-size:12.5px}
   .ok{background:#16a34a;color:#fff}.no{background:#dc2626;color:#fff}
-  .bar{padding:6px 14px;font-size:10.5px;color:#64748b;border-top:1px solid #262b38}
-  .in{display:flex;gap:8px;padding:10px 12px;border-top:1px solid #262b38}
-  .in input{flex:1;padding:9px 13px;background:#0f1117;border:1px solid #334155;border-radius:10px;color:#e2e8f0;font-size:13.5px;outline:none}
+  .bar{padding:8px 28px;font-size:11px;color:#94a3b8;border-top:1px solid #e2e8f0}
+  .in{display:flex;gap:10px;padding:16px 28px;border-top:1px solid #e2e8f0}
+  .in input{flex:1;padding:11px 15px;background:#f8fafc;border:1px solid #cbd5e1;border-radius:10px;color:#0f172a;font-size:14px;outline:none}
   .in input:focus{border-color:#2563eb}
-  .in button{padding:9px 16px;background:#2563eb;color:#fff;border:none;border-radius:10px;font-weight:600;cursor:pointer;font-size:13px}
-  .in button:disabled{background:#334155;cursor:not-allowed}
+  .in button{padding:11px 20px;background:#2563eb;color:#fff;border:none;border-radius:10px;font-weight:600;cursor:pointer;font-size:14px}
+  .in button:disabled{background:#cbd5e1;cursor:not-allowed}
+
+  @media (max-width:760px){
+    .layout{grid-template-columns:1fr}
+    .sidebar{grid-column:1;border-right:none;border-bottom:1px solid #e2e8f0}
+    .chat{grid-column:1}
+  }
 </style></head><body>
 
-<div class="landing">
-  <div class="card">
+<div class="layout">
+  <div class="sidebar">
     <h1>Welcome</h1>
-    <p>Sign in to get personalized help, or just open the chat to ask a question.</p>
+    <p>Sign in to get personalized help, or just start typing on the right to ask a question.</p>
     <div id="loginForm">
       <div class="field"><label>Your name</label><input id="lname" placeholder="e.g. Rhea Laloo"></div>
       <div class="field"><label>Employee ID (optional)</label><input id="lid" placeholder="e.g. E-1042"></div>
       <button onclick="signIn()">Continue</button>
     </div>
-    <div class="signedin" id="signedIn">Signed in as <b id="signedName"></b>. Use the chat button to start.</div>
+    <div class="signedin" id="signedIn">Signed in as <b id="signedName"></b>.</div>
+    <div class="meta-block" id="metaBlock"></div>
   </div>
-</div>
-
-<div class="launcher" id="launcher" onclick="togglePanel()">
-  <svg viewBox="0 0 24 24"><path d="M4 4h16a1 1 0 0 1 1 1v11a1 1 0 0 1-1 1H8l-4.4 3.3A1 1 0 0 1 2 19.5V5a1 1 0 0 1 1-1h1z"/></svg>
-  <div class="dot"></div>
-</div>
 
-<div class="panel" id="panel">
-  <div class="phead">
-    <div><div class="t">roscoe run</div><div class="s" id="meta">agent chat</div></div>
-    <div class="pclose" onclick="togglePanel()">&times;</div>
-  </div>
-  <div class="msgs" id="msgs"><div class="m bot">Hi — I'm your agent. Ask me anything.</div></div>
-  <div class="bar" id="bar">ready</div>
-  <div class="in">
-    <input id="q" placeholder="Type a message…" onkeydown="if(event.key==='Enter')send()">
-    <button id="btn" onclick="send()">Send</button>
+  <div class="chat">
+    <div class="chead">
+      <div><div class="t">roscoe run</div><div class="s">agent chat</div></div>
+    </div>
+    <div class="msgs" id="msgs"><div class="m bot">Hi — I'm your agent. Ask me anything.</div></div>
+    <div class="bar" id="bar">ready</div>
+    <div class="in">
+      <input id="q" placeholder="Type a message…" onkeydown="if(event.key==='Enter')send()">
+      <button id="btn" onclick="send()">Send</button>
+    </div>
   </div>
 </div>
 
 <script>
 const msgs=document.getElementById('msgs'),q=document.getElementById('q'),btn=document.getElementById('btn'),bar=document.getElementById('bar');
-const panel=document.getElementById('panel');
-let awaiting=false,userId='web-user',opened=false;
+let awaiting=false,userId='web-user';
 
 function signIn(){
   const name=document.getElementById('lname').value.trim();
@@ -225,11 +232,14 @@ function signIn(){
   document.getElementById('loginForm').style.display='none';
   const s=document.getElementById('signedIn');s.style.display='block';
   document.getElementById('signedName').textContent=name||'guest';
-  if(!opened)togglePanel();
+  q.focus();
 }
-function togglePanel(){opened=!opened;panel.classList.toggle('open',opened);if(opened)q.focus()}
 
-function add(cls,txt){const d=document.createElement('div');d.className='m '+cls;d.textContent=txt;msgs.appendChild(d);msgs.scrollTop=msgs.scrollHeight;return d}
+function add(cls,txt){
+  const d=document.createElement('div');d.className='m '+cls;
+  if(cls==='bot'&&window.marked){d.innerHTML=marked.parse(txt||'')}else{d.textContent=txt}
+  msgs.appendChild(d);msgs.scrollTop=msgs.scrollHeight;return d
+}
 function esc(s){const d=document.createElement('div');d.textContent=s==null?'':s;return d.innerHTML}
 function lock(on){btn.disabled=on;q.disabled=on}
 function showTyping(){const d=document.createElement('div');d.className='typing';d.innerHTML='<span></span><span></span><span></span>';msgs.appendChild(d);msgs.scrollTop=msgs.scrollHeight;return d}
@@ -252,11 +262,25 @@ function handle(ev){
   else if(ev.type==='error'){add('err',ev.error);bar.textContent='error'}
   else if(ev.type==='paused'){showApprove(ev)}
 }
+function fmtVal(v){
+  const s=typeof v==='string'?v:JSON.stringify(v);
+  return s.length>160?s.slice(0,160)+'…':s;
+}
 function showApprove(ev){
   awaiting=true;bar.textContent='awaiting approval';
   const box=document.createElement('div');box.className='approve';
   let html='<b>&#9208; approval required</b>';
-  (ev.tool_calls||[]).forEach(tc=>{html+='<div class="tc">'+esc(tc.name)+'('+esc(JSON.stringify(tc.args||{}))+')</div>'});
+  (ev.tool_calls||[]).forEach(tc=>{
+    html+='<div class="tc"><div class="tc-name">'+esc(tc.name)+'</div>';
+    const args=tc.args||{};
+    const keys=Object.keys(args);
+    if(keys.length){
+      html+='<table class="tc-args">'+keys.map(k=>
+        '<tr><td class="tc-k">'+esc(k)+'</td><td class="tc-v">'+esc(fmtVal(args[k]))+'</td></tr>'
+      ).join('')+'</table>';
+    }
+    html+='</div>';
+  });
   html+='<button class="ok">Approve</button><button class="no">Reject</button>';
   box.innerHTML=html;msgs.appendChild(box);msgs.scrollTop=msgs.scrollHeight;
   box.querySelector('.ok').onclick=()=>decide('approve',box);

roscoe-2.2.0/roscoe/cli/scaffold/agent_config.yaml

@@ -0,0 +1,36 @@
+# roscoe agent configuration — __PROJECT_NAME__
+# Full reference for every option below: docs.md (scaffolded alongside this file).
+# ${VAR_NAME} anywhere in this file resolves from your shell env or .env.
+
+agent_name: __PROJECT_NAME__
+system_prompt_file: prompts/system.txt
+# ui_script: app.py             # custom web UI `roscoe run` launches instead of
+                                 # the built-in widget (defaults to app.py if present)
+
+model:
+  provider: openai               # openai | azure_openai | anthropic | gemini | nvidia | ollama
+  model: gpt-4o-mini
+  api_key: ${OPENAI_API_KEY}
+  temperature: 0.1               # 0.0 = precise, 1.0 = creative
+
+memory:
+  conversation:
+    enabled: true
+    window_size: 10              # messages kept per session
+  persistent:
+    enabled: false                # long-term facts per user_id
+    backend: sqlite
+    connection: ./facts.db
+
+middleware:
+  retry:
+    max_attempts: 3
+  rate_limiter:
+    enabled: true
+    requests_per_minute: 60
+  cost_tracking:
+    enabled: true                 # result.cost_usd — see `roscoe prices` in docs.md
+  audit:
+    enabled: true                 # logs/audit.jsonl — feeds `roscoe monitor`
+  # human_approval:
+  #   require_approval_for: [send_email, delete_record]   # gate sensitive tools

{roscoe-2.0.0 → roscoe-2.2.0}/roscoe/cli/scaffold/docs.md

@@ -10,21 +10,22 @@ directly — they all work with the scaffolded project structure.
 ## Table of contents
 
 1. [Project structure](#project-structure)
-2. [Writing tools](#writing-tools)
-3. [Running the agent](#running-the-agent)
-4. [Multi-turn conversations](#multi-turn-conversations)
-5. [Swapping LLM providers](#swapping-llm-providers)
-6. [Memory](#memory)
-7. [Connectors](#connectors)
-8. [Human-in-the-loop (HITL)](#human-in-the-loop-hitl)
-9. [Audit log & cost tracking](#audit-log--cost-tracking)
-10. [Monitoring dashboard](#monitoring-dashboard)
-11. [Alerts & exporters](#alerts--exporters)
-12. [Evals](#evals)
-13. [Extending the cost table](#extending-the-cost-table)
-14. [Configuration reference](#configuration-reference)
-15. [Async usage](#async-usage)
-16. [Troubleshooting](#troubleshooting)
+2. [Available templates](#available-templates)
+3. [Writing tools](#writing-tools)
+4. [Running the agent](#running-the-agent)
+5. [Multi-turn conversations](#multi-turn-conversations)
+6. [Swapping LLM providers](#swapping-llm-providers)
+7. [Memory](#memory)
+8. [Connectors](#connectors)
+9. [Human-in-the-loop (HITL)](#human-in-the-loop-hitl)
+10. [Audit log & cost tracking](#audit-log--cost-tracking)
+11. [Monitoring dashboard](#monitoring-dashboard)
+12. [Alerts & exporters](#alerts--exporters)
+13. [Evals](#evals)
+14. [Extending the cost table](#extending-the-cost-table)
+15. [Configuration reference](#configuration-reference)
+16. [Async usage](#async-usage)
+17. [Troubleshooting](#troubleshooting)
 
 ---
 
@@ -46,6 +47,36 @@ __PROJECT_NAME__/
 
 ---
 
+## Available templates
+
+This project was scaffolded from one of roscoe's six built-in templates (or from
+scratch, if you didn't pass `--template`). Each one ships with tools, a system
+prompt, `agent_config.yaml`, and approval gates already wired up — a starting
+point you can rename and extend, not a locked-in structure.
+
+```bash
+roscoe init my-hr-bot --template hr_agent
+roscoe init my-it-bot --template it_support_agent
+roscoe init my-legal --template legal_agent
+roscoe init my-kb --template knowledge_base_agent
+roscoe init my-ea --template exec_assistant_agent
+roscoe init my-gws --template google_workspace_agent
+```
+
+| Template | Use case | Connector | Approval gate |
+|---|---|---|---|
+| `hr_agent` | Leave, payslips, personal details | REST API | `submit_leave_request` |
+| `it_support_agent` | Tickets, escalation, KB search | ServiceNow | `escalate_ticket` |
+| `legal_agent` | Contract search, clause extraction, risk flags | Knowledge (RAG) | — |
+| `knowledge_base_agent` | Q&A over Notion / SharePoint / docs | Notion + Knowledge | — (read-only) |
+| `exec_assistant_agent` | Email, calendar, availability | Outlook (MS Graph) | `send_email`, `create_event` |
+| `google_workspace_agent` | Gmail, Calendar, Tasks, Drive | Google Workspace (service account or OAuth2) | `send_email`, `create_event`, `create_task` |
+
+Mixing templates is fine too — copy a tool or connector wiring from another
+template's `tools/my_tools.py` into this project instead of starting a new one.
+
+---
+
 ## Writing tools
 
 A tool is a plain Python function with type hints and a docstring:
@@ -83,7 +114,21 @@ TOOLS = [get_weather, search_docs]
 
 ## Running the agent
 
-**Single-shot:**
+**From the CLI** — the fastest way to try the agent, no code needed:
+
+```bash
+roscoe run                    # browser chat (opens automatically)
+roscoe run --terminal         # interactive chat in the terminal, streamed
+roscoe run -m "your message"  # one-shot message, prints the reply, exits
+```
+
+If this project has its own web UI script (`app.py`, or whatever `ui_script:`
+names in `agent_config.yaml`), `roscoe run` launches that instead of the
+built-in browser widget — so a custom login page or dashboard just works with
+no flags. `--terminal` and `-m` always talk to the agent directly and never
+touch a custom UI script.
+
+**From Python — single-shot:**
 
 ```python
 from roscoe import AgentRunner
@@ -169,6 +214,14 @@ model:
   api_key: ${GOOGLE_API_KEY}
 ```
 
+**NVIDIA NIM (free-tier models available):**
+```yaml
+model:
+  provider: nvidia
+  model: openai/gpt-oss-120b
+  api_key: ${NVIDIA_API_KEY}
+```
+
 **Azure OpenAI:**
 ```yaml
 model:
@@ -273,7 +326,7 @@ agent = AgentRunner.from_config("agent_config.yaml", tools=TOOLS + jira.tools)
 | SharePoint | `SharePointConnector` | `client_id`, `client_secret`, `tenant_id`, `site_id` |
 | GitHub | `GitHubConnector` | `token` |
 | Notion | `NotionConnector` | `token` |
-| Google Workspace | `GoogleWorkspaceConnector` | `credentials_file`, `subject` |
+| Google Workspace | `GoogleWorkspaceConnector` | `credentials_file`, `subject` (service account) — or `client_id`, `client_secret`, `refresh_token` (OAuth2, minted via `roscoe google-auth`) |
 | Snowflake | `SnowflakeConnector` | `account`, `user`, `password`, `warehouse`, `database` |
 
 All connectors accept an optional `transport` parameter for mocking in tests:
@@ -551,7 +604,18 @@ print(diff.deltas)       # per-scorer, per-case score differences
 
 ## Extending the cost table
 
-roscoe ships with rates for common models. Add your own before calling `agent.run()`:
+roscoe ships with rates for common models. NVIDIA and Ollama default to $0.00
+(free-tier), so `nvidia`/`openai/gpt-oss-120b` and similar have no cost until
+you price them.
+
+**From the CLI** (writes to `~/.roscoe/prices.json`, applied on every run):
+
+```bash
+roscoe prices              # desktop editor — add/edit rates per provider+model
+roscoe prices --terminal   # print the effective price table instead
+```
+
+**From Python** (in-process only, before calling `agent.run()`):
 
 ```python
 from roscoe.middleware.cost_tracker import COST_TABLE
@@ -579,10 +643,13 @@ agent_name: my-agent                          # used in audit logs and monitorin
 system_prompt_file: prompts/system.txt        # path to system prompt file
 # system_prompt: |                            # or inline
 #   You are a helpful assistant.
+# ui_script: app.py                           # custom web UI `roscoe run` launches instead
+#                                              # of the built-in widget (defaults to app.py
+#                                              # if that file exists, even without this key)
 
 # --- LLM provider ---
 model:
-  provider: openai                            # openai | azure_openai | anthropic | gemini | ollama
+  provider: openai                            # openai | azure_openai | anthropic | gemini | nvidia | ollama
   model: gpt-4o-mini                          # model name
   api_key: ${OPENAI_API_KEY}                  # resolved from environment
   temperature: 0.1                            # 0.0–2.0

{roscoe-2.0.0 → roscoe-2.2.0}/roscoe/cli/wizard_gui.py

@@ -19,6 +19,7 @@ _PROVIDERS = [
     ("Azure OpenAI", "azure_openai"),
     ("Anthropic", "anthropic"),
     ("Gemini", "gemini"),
+    ("NVIDIA  (NIM, free-tier models available)", "nvidia"),
     ("Ollama  (free, local, no API key)", "ollama"),
 ]
 
@@ -28,6 +29,7 @@ _DEFAULT_MODELS = {
     "azure_openai": "gpt-4o",
     "anthropic": "claude-sonnet-4-5",
     "gemini": "gemini-1.5-pro",
+    "nvidia": "openai/gpt-oss-120b",
     "ollama": "llama3.1",
 }
 
@@ -37,6 +39,7 @@ _ENV_KEYS = {
     "azure_openai": "AZURE_OPENAI_KEY",
     "anthropic": "ANTHROPIC_API_KEY",
     "gemini": "GOOGLE_API_KEY",
+    "nvidia": "NVIDIA_API_KEY",
     "ollama": None,
 }
 

{roscoe-2.0.0 → roscoe-2.2.0/roscoe.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roscoe
-Version: 2.0.0
+Version: 2.2.0
 Summary: roscoe — Ready-to-run Orchestration SDK: Configurable, Observable, Extensible.
 Author-email: rhealaloo <rhealaloo@gmail.com>
 License-Expression: MIT

roscoe-2.0.0/roscoe/cli/scaffold/agent_config.yaml

@@ -1,188 +0,0 @@
-# =============================================================================
-# roscoe agent configuration — __PROJECT_NAME__
-# =============================================================================
-#
-# This is the only file you need to configure. Everything below is read by
-# AgentRunner.from_config() and wired automatically — no boilerplate code.
-#
-# Environment variables: use ${VAR_NAME} anywhere in this file. Values are
-# resolved from your shell environment (or a .env file if you load one).
-#
-# Docs: https://github.com/rhealaloo45/roscoe
-# =============================================================================
-
-
-# ---------- Agent identity ---------------------------------------------------
-
-agent_name: __PROJECT_NAME__
-
-# The system prompt tells the LLM who it is and how to behave.
-# Inline string or point to a file:
-system_prompt_file: prompts/system.txt
-# system_prompt: |
-#   You are a helpful assistant. Be concise.
-
-# `roscoe run` opens a generic browser chat by default. If this project has
-# its own web UI (a Flask app that builds the agent itself — custom login,
-# dashboard, branded chat), roscoe defers to it instead: it looks for
-# `app.py` in this directory and just runs it. Only set this if your file
-# is named something else:
-# ui_script: app.py
-
-
-# ---------- Model ------------------------------------------------------------
-# Swap providers by changing this block. Your Python code stays identical.
-#
-# Supported providers:
-#   openai        — GPT-4o, GPT-4o-mini, etc.
-#   azure_openai  — Azure-hosted OpenAI (needs deployment + endpoint)
-#   anthropic     — Claude Sonnet, Opus, Haiku
-#   gemini        — Gemini 1.5 Pro / Flash
-#   ollama        — any local model (free, no API key)
-#
-# OpenAI-compatible endpoints (OpenRouter, Together, etc.):
-#   provider: openai
-#   base_url: https://openrouter.ai/api/v1
-#   model: meta-llama/llama-3.1-8b-instruct
-
-model:
-  provider: openai
-  model: gpt-4o-mini
-  api_key: ${OPENAI_API_KEY}
-  temperature: 0.1
-  # max_tokens: 4096            # cap the response length
-
-  # --- Azure OpenAI example (uncomment & replace the block above) ---
-  # provider: azure_openai
-  # deployment: my-gpt4o-deployment
-  # endpoint: ${AZURE_OPENAI_ENDPOINT}
-  # api_key: ${AZURE_OPENAI_KEY}
-  # api_version: "2024-02-01"
-
-  # --- Anthropic example ---
-  # provider: anthropic
-  # model: claude-sonnet-4-5
-  # api_key: ${ANTHROPIC_API_KEY}
-
-  # --- Gemini example ---
-  # provider: gemini
-  # model: gemini-1.5-pro
-  # api_key: ${GOOGLE_API_KEY}
-
-  # --- Ollama (local, free, no key) ---
-  # provider: ollama
-  # model: llama3.1
-
-
-# ---------- Memory -----------------------------------------------------------
-# Conversation = short-term (per session_id, windowed).
-# Persistent   = long-term facts per user_id, stored in sqlite.
-# Knowledge    = RAG retrieval (FAISS or keyword). Set up in code, not here.
-
-memory:
-  conversation:
-    enabled: true
-    window_size: 10             # keep last N messages per session
-
-  persistent:
-    enabled: false              # flip to true to enable cross-session memory
-    backend: sqlite
-    connection: ./facts.db      # file path, or ":memory:" for throwaway
-    # max_facts: 50             # cap stored facts per user (default: unlimited)
-
-
-# ---------- Middleware -------------------------------------------------------
-# All middleware is automatic — set it here, forget about it in code.
-
-middleware:
-
-  # Retry — retries failed LLM calls with exponential backoff.
-  # Handles transient errors (rate limits, timeouts, 500s) automatically.
-  retry:
-    max_attempts: 3             # total attempts (1 = no retry)
-    # wait_multiplier: 1        # backoff multiplier in seconds
-    # wait_max: 10              # max wait between retries
-
-  # Rate limiter — token-bucket per provider. Prevents thrashing API limits
-  # when multiple agents share the same provider.
-  # Ollama is always skipped (no external limit).
-  rate_limiter:
-    enabled: true
-    requests_per_minute: 60     # adjust based on your API tier
-    # rpm: 60                   # alias for requests_per_minute
-
-  # Cost tracking — estimates USD cost from token counts.
-  # Shows up in result.cost_usd and the audit log.
-  # Built-in rates: gpt-4o, gpt-4o-mini, claude-sonnet-4-5, gemini-1.5-pro.
-  # Prices drift — add or correct your own rates for ANY provider (no code):
-  #   roscoe prices           # desktop editor, saves to ~/.roscoe/prices.json
-  cost_tracking:
-    enabled: true
-
-  # Tool guardrails — hard timeout per tool call, plus an error budget so a
-  # failing tool is refused instead of retried every iteration. Both optional.
-  # tools:
-  #   timeout_seconds: 30       # kill a single tool call after N seconds
-  #   max_failures: 3           # disable a tool for the run after N failures
-
-  # Audit logging — writes one JSONL line per run to logs/audit.jsonl.
-  # Non-blocking (async). Contains: run_id, agent, provider, model, tokens,
-  # cost, status, latency. Feed to `roscoe monitor` for dashboards.
-  audit:
-    enabled: true
-    # path: logs/audit.jsonl    # default path; override if needed
-
-  # Human approval — pause the agent before running sensitive tools.
-  # The run returns status="paused"; call agent.resume(run_id, "approve")
-  # to continue, or "reject" / "modify" to block / change args.
-  # human_approval:
-  #   require_approval_for:
-  #     - send_email             # tool function names that need sign-off
-  #     - delete_record
-  #     - submit_payment
-
-
-# ---------- Connectors (optional) --------------------------------------------
-# Connectors are pre-built tool bundles for common services.
-# Set them up in code, not in this file:
-#
-#   from roscoe.connectors import GitHubConnector
-#   gh = GitHubConnector({"token": "ghp_..."})
-#   agent = AgentRunner.from_config("agent_config.yaml", tools=gh.tools)
-#
-# Available connectors:
-#   RESTConnector        — any REST API (base_url + token)
-#   JiraConnector        — Jira Cloud (email + api_token)
-#   ServiceNowConnector  — ServiceNow (instance_url + user/pass)
-#   OutlookConnector     — Microsoft Graph email/calendar
-#   SharePointConnector  — Microsoft Graph files
-#   GitHubConnector      — GitHub API (PAT)
-#   NotionConnector      — Notion API (integration token)
-#   GoogleWorkspaceConnector — Gmail + Calendar + Tasks + Drive (service account)
-#   SnowflakeConnector   — Snowflake SQL (pip install roscoe[snowflake])
-#
-# Mix connector tools with your own:
-#   tools = [my_tool] + gh.tools + jira.tools
-
-
-# ---------- Monitoring (optional) --------------------------------------------
-# After runs accumulate, use the CLI to view a dashboard:
-#   roscoe monitor --path logs/audit.jsonl
-#
-# Export to Prometheus Pushgateway or Azure Monitor in code:
-#   from roscoe.monitoring.exporters.prometheus import PrometheusPushgatewayExporter
-#   exporter = PrometheusPushgatewayExporter(gateway_url="http://localhost:9091")
-#   exporter.push(metrics)
-
-
-# ---------- Evals (optional) -------------------------------------------------
-# Define test cases in evals/test_cases.json (already scaffolded).
-# Run from CLI:
-#   roscoe eval --dataset evals/test_cases.json --config agent_config.yaml
-#
-# Add --judge to enable LLM-as-judge scoring (output quality + hallucination).
-# Without --judge, only deterministic tool-usage scoring runs.
-#
-# Compare two runs for regressions:
-#   from roscoe.evals.regression import compare_runs
-#   diff = compare_runs(report_a, report_b)