padwan-cli 0.4.0__tar.gz → 0.6.0__tar.gz

padwan_cli-0.6.0/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.3
+Name: padwan-cli
+Version: 0.6.0
+Summary: CLI and TUI for padwan-llm
+Author-email: julien.brayere@polarsen.com
+Requires-Dist: padwan-llm[realtime]>=0.9.0
+Requires-Dist: piou[tui]>=0.36.0
+Requires-Dist: tracktolib>=0.74.0
+Requires-Dist: padwan-llm[langfuse]>=0.9.0 ; extra == 'langfuse'
+Requires-Dist: padwan-llm[otel]>=0.9.0 ; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.44 ; extra == 'otel'
+Requires-Dist: opentelemetry-exporter-otlp>=1.44 ; extra == 'otel'
+Requires-Dist: sounddevice>=0.5 ; extra == 'voice'
+Requires-Python: >=3.14
+Provides-Extra: langfuse
+Provides-Extra: otel
+Provides-Extra: voice
+Description-Content-Type: text/markdown
+
+# Padwan CLI
+
+Interactive CLI/TUI for [`padwan-llm`](https://github.com/polarsen-io/padwan-llm).
+
+> [!NOTE]
+> This is a playground for experimenting with `padwan-llm` features (streaming, agents, MCP, thinking tokens, batch jobs, realtime voice) — not a production-grade tool. Expect rough edges and breaking changes.
+
+<img alt="Chat demo" src="https://github.com/polarsen-io/padwan-cli/raw/master/docs/static/chat.gif" width="800"/>
+
+## Quick start
+
+```bash
+export OPENAI_API_KEY=...
+uvx padwan-cli
+# then /help for commands
+```
+
+
+## Install
+
+```bash
+pip install padwan-cli
+```
+
+## Local Development
+
+```bash
+uv sync --group dev
+uv run padwan-cli
+```
+
+## One-shot Mode
+
+```bash
+uvx padwan-cli "Hello" -m gpt-4o-mini
+
+# attach files (images/audio/text, routed by type)
+uvx padwan-cli "What's in this recording?" -m gpt-4o-audio-preview -f clip.mp3
+```
+
+## Voice Mode
+
+Real-time speech-to-speech chat (needs the PortAudio system lib, e.g. `libportaudio2`):
+
+```bash
+uvx --from "padwan-cli[voice]" padwan-talk
+```
+
+## Tracing
+
+Pass `--trace <backend>` (on the one-shot, `chat send`, and `talk` commands) to instrument all LLM calls with [padwan-llm's OTel GenAI telemetry](https://github.com/polarsen-io/padwan-llm/blob/master/docs/observability.md):
+
+```bash
+# Langfuse, using the standard LANGFUSE_* env vars
+export LANGFUSE_PUBLIC_KEY=... LANGFUSE_SECRET_KEY=... LANGFUSE_BASE_URL=...
+uvx --from "padwan-cli[langfuse]" padwan-cli "Hello" --trace langfuse
+
+# any OTLP collector, using the standard OTEL_EXPORTER_OTLP_* env vars
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
+  uvx --from "padwan-cli[otel]" padwan-cli "Hello" --trace otlp
+```
+

padwan_cli-0.6.0/README.md

@@ -0,0 +1,62 @@
+# Padwan CLI
+
+Interactive CLI/TUI for [`padwan-llm`](https://github.com/polarsen-io/padwan-llm).
+
+> [!NOTE]
+> This is a playground for experimenting with `padwan-llm` features (streaming, agents, MCP, thinking tokens, batch jobs, realtime voice) — not a production-grade tool. Expect rough edges and breaking changes.
+
+<img alt="Chat demo" src="https://github.com/polarsen-io/padwan-cli/raw/master/docs/static/chat.gif" width="800"/>
+
+## Quick start
+
+```bash
+export OPENAI_API_KEY=...
+uvx padwan-cli
+# then /help for commands
+```
+
+
+## Install
+
+```bash
+pip install padwan-cli
+```
+
+## Local Development
+
+```bash
+uv sync --group dev
+uv run padwan-cli
+```
+
+## One-shot Mode
+
+```bash
+uvx padwan-cli "Hello" -m gpt-4o-mini
+
+# attach files (images/audio/text, routed by type)
+uvx padwan-cli "What's in this recording?" -m gpt-4o-audio-preview -f clip.mp3
+```
+
+## Voice Mode
+
+Real-time speech-to-speech chat (needs the PortAudio system lib, e.g. `libportaudio2`):
+
+```bash
+uvx --from "padwan-cli[voice]" padwan-talk
+```
+
+## Tracing
+
+Pass `--trace <backend>` (on the one-shot, `chat send`, and `talk` commands) to instrument all LLM calls with [padwan-llm's OTel GenAI telemetry](https://github.com/polarsen-io/padwan-llm/blob/master/docs/observability.md):
+
+```bash
+# Langfuse, using the standard LANGFUSE_* env vars
+export LANGFUSE_PUBLIC_KEY=... LANGFUSE_SECRET_KEY=... LANGFUSE_BASE_URL=...
+uvx --from "padwan-cli[langfuse]" padwan-cli "Hello" --trace langfuse
+
+# any OTLP collector, using the standard OTEL_EXPORTER_OTLP_* env vars
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
+  uvx --from "padwan-cli[otel]" padwan-cli "Hello" --trace otlp
+```
+

{padwan_cli-0.4.0 → padwan_cli-0.6.0}/padwan_cli/chat.py

@@ -1,8 +1,10 @@
 import contextlib
 import json
+import mimetypes
 import time
 from contextlib import contextmanager
-from typing import Any
+from pathlib import Path
+from typing import Any, cast, get_args
 
 from piou import Option, CommandGroup
 from piou.tui import PromptStyle, TuiContext, TuiOption
@@ -10,22 +12,35 @@ from textual.css.query import NoMatches
 
 from padwan_llm import (
     AgentSession,
+    ContentPart,
     ConversationSnapshot,
     LLMClient,
     McpStreamable,
     McpTool,
     McpTransport,
     ToolCallContext,
+    audio_part,
+    image_part,
+    supports_audio,
+    supports_vision,
+    text_file_part,
+    text_part,
 )
+from padwan_llm.content import AudioFormat
 from padwan_llm.gemini import GeminiClient
 from padwan_llm.gemini.models import ThinkingConfig
+from .trace import TRACE_BACKENDS, TraceBackend, enable_tracing
 from .utils import ALL_MODELS, console
 from .widgets import (
+    Attachment,
+    AttachmentBadge,
+    AttachmentKind,
     ErrorMessage,
     StreamingMessage,
     ThoughtMessage,
     ToolCallMessage,
     UserMessage,
+    render_attachments,
 )
 
 chat_group = CommandGroup(name="chat", help="Chat with an LLM")
@@ -85,6 +100,76 @@ def _format_tokens(session: AgentSession, ctx: TuiContext | None = None) -> str:
     return " ".join(parts)
 
 
+_AUDIO_FORMATS: tuple[AudioFormat, ...] = get_args(AudioFormat)
+_KIND_LABELS = {"image": "images", "audio": "audio", "text": "files"}
+
+
+def _audio_fmt(path: Path) -> AudioFormat | None:
+    """Derive the audio format from the file extension, if it is a known one."""
+    fmt = path.suffix.removeprefix(".").lower()
+    return cast(AudioFormat, fmt) if fmt in _AUDIO_FORMATS else None
+
+
+def _unsupported_warning(
+    model: str, attachments: list[Attachment], *, suffix: str
+) -> str | None:
+    """Amber warning line for attachments the model can't consume, or None."""
+    skipped = [a for a in attachments if not a.supported]
+    if not skipped:
+        return None
+    kinds = "/".join(dict.fromkeys(_KIND_LABELS[a.kind] for a in skipped))
+    return f"{model} can't read {kinds} — {len(skipped)} {suffix}"
+
+
+def _build_user_content(
+    text: str, attachments: list[Attachment]
+) -> str | list[ContentPart]:
+    """Assemble the user turn from typed text and queued attachments.
+
+    Returns the plain string when nothing is attached. Otherwise builds content
+    parts: the text, each text file inlined, and each supported image or audio
+    file as a data payload. Unsupported media (model can't see/hear it) and
+    unreadable files are dropped from the payload — they still appear in the
+    sent badge.
+    """
+    if not attachments:
+        return text
+    parts: list[ContentPart] = []
+    if text:
+        parts.append(text_part(text))
+    for a in attachments:
+        if not a.supported:
+            continue
+        if a.kind == "image":
+            parts.append(image_part(a.path))
+        elif a.kind == "audio":
+            try:
+                parts.append(audio_part(a.path))
+            except OSError, ValueError:
+                continue
+        else:
+            try:
+                parts.append(text_file_part(a.path))
+            except OSError, UnicodeDecodeError:
+                continue
+    return parts
+
+
+def _parse_extra_params(raw: str | None) -> tuple[dict[str, Any] | None, bool]:
+    """Parse --extra-params JSON; print the error and return ok=False on failure."""
+    if raw is None:
+        return None, True
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError as e:
+        console.print(f"[red]--extra-params is not valid JSON: {e}[/red]")
+        return None, False
+    if not isinstance(parsed, dict):
+        console.print("[red]--extra-params must be a JSON object[/red]")
+        return None, False
+    return parsed, True
+
+
 @chat_group.command("send", help="Send a message to the LLM")
 async def chat_send_fn(
     message: str = Option(..., help="Message to send"),
@@ -106,6 +191,12 @@ async def chat_send_fn(
         "--mcp",
         help=f"Streamable-HTTP MCP server URL(s) to expose as tools (e.g. {DATAGOUV_MCP_URL})",
     ),
+    trace: TraceBackend | None = Option(
+        None,
+        "--trace",
+        help="Export LLM telemetry to this backend",
+        choices=TRACE_BACKENDS,
+    ),
     ctx: TuiContext = TuiOption(),
 ) -> None:
     """Start a conversation. Use Ctrl+C to exit."""
@@ -158,16 +249,12 @@ async def chat_send_fn(
         else:
             console.print(f"[green]MCP connected[/green] [dim]{transport.label}[/dim]")
 
-    parsed_extra: dict[str, Any] | None = None
-    if extra_params is not None:
-        try:
-            parsed_extra = json.loads(extra_params)
-        except json.JSONDecodeError as e:
-            console.print(f"[red]--extra-params is not valid JSON: {e}[/red]")
-            return
-        if not isinstance(parsed_extra, dict):
-            console.print("[red]--extra-params must be a JSON object[/red]")
-            return
+    parsed_extra, ok = _parse_extra_params(extra_params)
+    if not ok:
+        return
+
+    if trace:
+        enable_tracing(trace)
 
     try:
         client = LLMClient(model=model, on_thought=_on_thought, base_url=base_url)
@@ -196,16 +283,81 @@ async def chat_send_fn(
             ctx.set_rule_above(add_class="chat-mode")
             ctx.set_rule_below(add_class="chat-mode")
 
+            # Files dropped onto the terminal arrive as a paste of their path(s);
+            # queue them here and send with the next typed message.
+            pending: list[Attachment] = []
+
+            def _set_attach_warning(on: bool) -> None:
+                """Turn the input bars amber (or back to chat-mode cyan)."""
+                add, remove = (
+                    ("attach-warning", "chat-mode")
+                    if on
+                    else ("chat-mode", "attach-warning")
+                )
+                ctx.set_rule_above(add_class=add, remove_class=remove)
+                ctx.set_rule_below(add_class=add, remove_class=remove)
+
+            def _on_drop(paths: list[Path]) -> None:
+                for p in paths:
+                    try:
+                        size = p.stat().st_size
+                    except OSError:
+                        continue
+                    mime = mimetypes.guess_type(p)[0] or ""
+                    kind: AttachmentKind
+                    if mime.startswith("image/"):
+                        kind, supported = "image", supports_vision(model)
+                    elif mime.startswith("audio/"):
+                        kind, supported = "audio", supports_audio(model, _audio_fmt(p))
+                    else:
+                        kind, supported = "text", True
+                    pending.append(
+                        Attachment(
+                            path=p,
+                            name=p.name,
+                            size=size,
+                            kind=kind,
+                            supported=supported,
+                        )
+                    )
+                warning = _unsupported_warning(model, pending, suffix="will be skipped")
+                ctx.set_attachments(render_attachments(pending, warning=warning))
+                _set_attach_warning(warning is not None)
+                ctx.set_hint(
+                    f"{len(pending)} attached — type a message · Ctrl+U clears"
+                )
+
+            def _on_clear() -> None:
+                pending.clear()
+                ctx.set_attachments(None)
+                _set_attach_warning(False)
+                ctx.set_hint("Chat mode - press Ctrl+C to exit")
+
+            ctx.register_paste_handler(_on_drop)
+            ctx.register_attachment_clear(_on_clear)
+
             try:
                 while user_input:
                     if ctx.is_tui:
+                        sent = list(pending)
                         ctx.mount_widget(UserMessage(user_input))
+                        if sent:
+                            badge_warning = _unsupported_warning(
+                                model, sent, suffix="skipped"
+                            )
+                            ctx.mount_widget(
+                                AttachmentBadge(sent, warning=badge_warning)
+                            )
+                        content = _build_user_content(user_input, sent)
+                        pending.clear()
+                        ctx.set_attachments(None)
+                        _set_attach_warning(False)
                         ctx.set_hint("Responding...")
                         ctx.set_silent_queue(True)
                         needs_new_text_widget = True
                         widget: StreamingMessage | None = None
                         try:
-                            async for chunk in session.stream(user_input):
+                            async for chunk in session.stream(content):
                                 if needs_new_text_widget or widget is None:
                                     widget = StreamingMessage()
                                     ctx.mount_widget(widget)
@@ -237,6 +389,8 @@ async def chat_send_fn(
                         break
             finally:
                 session.save()
+                ctx.register_paste_handler(None)
+                ctx.register_attachment_clear(None)
                 # Cleanup is best-effort — on a double-Ctrl+C the TUI screen
                 # is already tearing down, so query_one("#status-above") and
                 # friends raise NoMatches. Don't surface that as a misleading
@@ -245,9 +399,12 @@ async def chat_send_fn(
                     ctx.set_silent_queue(False)
                     ctx.clear_queue()  # Discard any messages typed during streaming
                     ctx.set_status_above(None)
+                    ctx.set_attachments(None)
                     ctx.set_hint(None)
                     ctx.set_rule_above(remove_class="chat-mode")
                     ctx.set_rule_below(remove_class="chat-mode")
+                    ctx.set_rule_above(remove_class="attach-warning")
+                    ctx.set_rule_below(remove_class="attach-warning")
                     if original_style:
                         ctx.set_prompt_style(original_style)
     except Exception as e:

{padwan_cli-0.4.0 → padwan_cli-0.6.0}/padwan_cli/run.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import json
 import sys
+from pathlib import Path
 from typing import Any
 
 from piou import Cli, Option
@@ -10,11 +11,14 @@ from piou.tui import get_tui_context
 from rich.table import Table
 
 from padwan_llm import (
+    ANTHROPIC_MODELS,
     GEMINI_MODELS,
     GROK_MODELS,
     MISTRAL_MODELS,
     OPENAI_MODELS,
+    ContentPart,
     LLMClient,
+    content_parts,
 )
 from padwan_llm._base import OnThought
 from padwan_llm.conversation import Message
@@ -23,11 +27,16 @@ from padwan_llm.errors import Provider
 from .utils import console
 from .batch import batch_group
 from .chat import chat_group
+from .talk import talk_command
+from .trace import TRACE_BACKENDS, TraceBackend, enable_tracing
 
 CUSTOM_CSS = """
 Rule.chat-mode {
     color: #87ceeb;
 }
+Rule.attach-warning {
+    color: #fbbf24;
+}
 """
 
 cli = Cli(description="Padwan CLI for the unified LLM client library")
@@ -35,6 +44,8 @@ cli = Cli(description="Padwan CLI for the unified LLM client library")
 cli.add_command_group(batch_group)
 cli.add_command_group(chat_group)
 
+cli.command("talk", help="Speech-to-speech voice chat")(talk_command)
+
 
 @cli.tui_on_ready
 def _tui_startup_hint() -> None:
@@ -58,6 +69,8 @@ def list_models(
         provider_models["Mistral"] = list(MISTRAL_MODELS)
     if not provider or provider == "grok":
         provider_models["Grok"] = list(GROK_MODELS)
+    if not provider or provider == "anthropic":
+        provider_models["Anthropic"] = list(ANTHROPIC_MODELS)
 
     if not provider_models:
         console.print(f"[red]Unknown provider: {provider}[/red]")
@@ -85,9 +98,14 @@ def info() -> None:
     table.add_row("Gemini", str(len(GEMINI_MODELS)))
     table.add_row("Mistral", str(len(MISTRAL_MODELS)))
     table.add_row("Grok", str(len(GROK_MODELS)))
+    table.add_row("Anthropic", str(len(ANTHROPIC_MODELS)))
 
     total = (
-        len(OPENAI_MODELS) + len(GEMINI_MODELS) + len(MISTRAL_MODELS) + len(GROK_MODELS)
+        len(OPENAI_MODELS)
+        + len(GEMINI_MODELS)
+        + len(MISTRAL_MODELS)
+        + len(GROK_MODELS)
+        + len(ANTHROPIC_MODELS)
     )
     table.add_section()
     table.add_row("[bold]Total[/bold]", f"[bold]{total}[/bold]")
@@ -113,6 +131,18 @@ async def oneshot(
         "--stream-thinking",
         help="Stream model reasoning/thinking tokens to stderr (requires --stream)",
     ),
+    files: list[Path] | None = Option(
+        None,
+        "-f",
+        "--file",
+        help="Attach file(s) to the prompt (images/audio/text, routed by type)",
+    ),
+    trace: TraceBackend | None = Option(
+        None,
+        "--trace",
+        help="Export LLM telemetry to this backend",
+        choices=TRACE_BACKENDS,
+    ),
 ) -> None:
     """Send a single prompt and print the response."""
     parsed_extra: dict[str, Any] | None = None
@@ -132,8 +162,19 @@ async def oneshot(
 
     on_thought: OnThought | None = _thought_streamer if stream_thinking else None
 
+    if trace:
+        enable_tracing(trace)
+
+    content: str | list[ContentPart] = prompt
+    if files:
+        try:
+            content = content_parts(prompt, *files)
+        except (OSError, ValueError) as e:
+            console.print(f"[red]--file: {e}[/red]")
+            raise SystemExit(1)
+
     client = LLMClient(model=model, base_url=base_url, on_thought=on_thought)
-    messages: list[Message] = [Message(role="user", content=prompt)]
+    messages: list[Message] = [Message(role="user", content=content)]
     async with client:
         if stream:
             async for chunk in client.stream_chat(messages, extra_params=parsed_extra):