chatterer 0.1.23__py3-none-any.whl → 0.1.25__py3-none-any.whl

chatterer/examples/pw.py

@@ -0,0 +1,143 @@
+import json
+import logging
+import sys
+from pathlib import Path
+
+from spargear import ArgumentSpec, BaseArguments, RunnableArguments, SubcommandSpec
+
+from chatterer import PlayWrightBot
+
+logger = logging.getLogger(__name__)
+
+
+def generate_json_path() -> Path:
+    return Path("session_state.json").resolve()
+
+
+class ReadArgs(RunnableArguments[None]):
+    """Arguments for the 'read' subcommand."""
+
+    URL: str
+    """URL (potentially protected) to navigate to using the saved session."""
+    json: ArgumentSpec[Path] = ArgumentSpec(
+        ["--json", "-j"],
+        default_factory=generate_json_path,
+        help="Path to the session state JSON file to load.",
+    )
+
+    def run(self) -> None:
+        """
+        Loads the session state from the specified JSON file, then navigates
+        to a protected_url that normally requires login. If the stored session
+        is valid, it should open without re-entering credentials.
+
+        Correction: Loads the JSON content into a dict first to satisfy type hints.
+        """
+        url = self.URL
+        jsonpath = self.json.unwrap()
+        logger.info(f"Loading session from {jsonpath} and navigating to {url} ...")
+
+        if not jsonpath.exists():
+            logger.error(f"Session file not found at {jsonpath}")
+            sys.exit(1)
+
+        # Load the storage state from the JSON file into a dictionary
+        logger.info(f"Reading storage state content from {jsonpath} ...")
+        try:
+            with open(jsonpath, "r", encoding="utf-8") as f:
+                # This dictionary should match the 'StorageState' type expected by Playwright/chatterer
+                storage_state_dict = json.load(f)
+        except json.JSONDecodeError:
+            logger.error(f"Failed to decode JSON from {jsonpath}")
+            sys.exit(1)
+        except Exception as e:
+            logger.error(f"Error reading file {jsonpath}: {e}")
+            sys.exit(1)
+
+        logger.info("Launching browser with loaded session state...")
+        with PlayWrightBot(
+            playwright_launch_options={"headless": False},
+            # Pass the loaded dictionary, which should match the expected 'StorageState' type
+            playwright_persistency_options={"storage_state": storage_state_dict},
+        ) as bot:
+            bot.get_page(url)
+
+            logger.info("Press Enter in the console when you're done checking the protected page.")
+            input("    >> Press Enter to exit: ")
+
+        logger.info("Done! Browser is now closed.")
+
+
+class WriteArgs(RunnableArguments[None]):
+    """Arguments for the 'write' subcommand."""
+
+    URL: str
+    """URL to navigate to for manual login."""
+    json: ArgumentSpec[Path] = ArgumentSpec(
+        ["--json", "-j"],
+        default_factory=generate_json_path,
+        help="Path to save the session state JSON file.",
+    )
+
+    def run(self) -> None:
+        """
+        Launches a non-headless browser and navigates to the login_url.
+        The user can manually log in, then press Enter in the console
+        to store the current session state into a JSON file.
+        """
+        url = self.URL
+        jsonpath = self.json.unwrap()
+        logger.info(f"Launching browser and navigating to {url} ... Please log in manually.")
+
+        # Ensure jsonpath directory exists
+        jsonpath.parent.mkdir(parents=True, exist_ok=True)
+
+        with PlayWrightBot(playwright_launch_options={"headless": False}) as bot:
+            bot.get_page(url)
+
+            logger.info("After completing the login in the browser, press Enter here to save the session.")
+            input("    >> Press Enter when ready: ")
+
+            # get_sync_browser() returns the BrowserContext internally
+            context = bot.get_sync_browser()
+
+            # Save the current session (cookies, localStorage) to a JSON file
+            logger.info(f"Saving storage state to {jsonpath} ...")
+            context.storage_state(path=jsonpath)  # Pass Path object directly
+
+        logger.info("Done! Browser is now closed.")
+
+
+class Arguments(BaseArguments):
+    """
+    A simple CLI tool for saving and using Playwright sessions via storage_state.
+    Uses spargear for declarative argument parsing.
+    """
+
+    read: SubcommandSpec[ReadArgs] = SubcommandSpec(
+        name="read",
+        argument_class=ReadArgs,
+        help="Use a saved session to view a protected page.",
+        description="Loads session state from the specified JSON file and navigates to the URL.",
+    )
+    write: SubcommandSpec[WriteArgs] = SubcommandSpec(
+        name="write",
+        argument_class=WriteArgs,
+        help="Save a new session by manually logging in.",
+        description="Launches a browser to the specified URL. Log in manually, then press Enter to save session state.",
+    )
+
+    def run(self) -> None:
+        """Parses arguments using spargear and executes the corresponding command."""
+        if isinstance(last_subcommand := self.last_command, RunnableArguments):
+            last_subcommand.run()
+        else:
+            self.get_parser().print_help()
+
+
+def main() -> None:
+    Arguments().run()
+
+
+if __name__ == "__main__":
+    main()

chatterer/examples/{get_code_snippets.py → snippet.py}

@@ -1,55 +1,56 @@
-import logging
-from pathlib import Path
-from typing import Optional
-
-from spargear import BaseArguments
-
-from chatterer import CodeSnippets
-
-logger = logging.getLogger(__name__)
-
-
-class GetCodeSnippetsArgs(BaseArguments):
-    input: str
-    """Path to the package or file from which to extract code snippets."""
-    output: Optional[str] = None
-    """Output path for the extracted code snippets. If not provided, defaults to a file with the same name as the input."""
-    ban_file_patterns: list[str] = [".venv/*", Path(__file__).relative_to(Path.cwd()).as_posix()]
-    """List of file patterns to ignore."""
-    glob_patterns: list[str] = ["*.py"]
-    """List of glob patterns to include."""
-    case_sensitive: bool = False
-    """Enable case-sensitive matching for glob patterns."""
-    prevent_save_file: bool = False
-    """Prevent saving the extracted code snippets to a file."""
-
-    def run(self) -> CodeSnippets:
-        if not self.prevent_save_file:
-            if not self.output:
-                output = Path(__file__).with_suffix(".txt")
-            else:
-                output = Path(self.output)
-        else:
-            output = None
-
-        cs = CodeSnippets.from_path_or_pkgname(
-            path_or_pkgname=self.input,
-            ban_file_patterns=self.ban_file_patterns,
-            glob_patterns=self.glob_patterns,
-            case_sensitive=self.case_sensitive,
-        )
-        if output is not None:
-            output.parent.mkdir(parents=True, exist_ok=True)
-            output.write_text(cs.snippets_text, encoding="utf-8")
-            logger.info(f"Extracted code snippets from `{self.input}` and saved to `{output}`.")
-        else:
-            logger.info(f"Extracted code snippets from `{self.input}`.")
-        return cs
-
-
-def main() -> None:
-    GetCodeSnippetsArgs().run()
-
-
-if __name__ == "__main__":
-    main()
+import logging
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from spargear import RunnableArguments
+
+from chatterer import CodeSnippets
+
+logger = logging.getLogger(__name__)
+
+
+class Arguments(RunnableArguments[CodeSnippets]):
+    PATH_OR_PACKAGE_NAME: str
+    """Path to the package or file from which to extract code snippets."""
+    output: Optional[str] = None
+    """Output path for the extracted code snippets. If not provided, defaults to a file with the current timestamp."""
+    ban_file_patterns: list[str] = [".venv/*", Path(__file__).relative_to(Path.cwd()).as_posix()]
+    """List of file patterns to ignore."""
+    glob_patterns: list[str] = ["*.py"]
+    """List of glob patterns to include."""
+    case_sensitive: bool = False
+    """Enable case-sensitive matching for glob patterns."""
+    prevent_save_file: bool = False
+    """Prevent saving the extracted code snippets to a file."""
+
+    def run(self) -> CodeSnippets:
+        if not self.prevent_save_file:
+            if not self.output:
+                output = Path(datetime.now().strftime("%Y%m%d_%H%M%S") + "_snippets.txt")
+            else:
+                output = Path(self.output)
+        else:
+            output = None
+
+        cs = CodeSnippets.from_path_or_pkgname(
+            path_or_pkgname=self.PATH_OR_PACKAGE_NAME,
+            ban_file_patterns=self.ban_file_patterns,
+            glob_patterns=self.glob_patterns,
+            case_sensitive=self.case_sensitive,
+        )
+        if output is not None:
+            output.parent.mkdir(parents=True, exist_ok=True)
+            output.write_text(cs.snippets_text, encoding="utf-8")
+            logger.info(f"Extracted code snippets from `{self.PATH_OR_PACKAGE_NAME}` and saved to `{output}`.")
+        else:
+            logger.info(f"Extracted code snippets from `{self.PATH_OR_PACKAGE_NAME}`.")
+        return cs
+
+
+def main() -> None:
+    Arguments().run()
+
+
+if __name__ == "__main__":
+    main()

chatterer/examples/transcribe.py

@@ -0,0 +1,192 @@
+# pyright: reportUnknownVariableType=false, reportUnknownMemberType=false, reportArgumentType=false, reportMissingTypeStubs=false
+
+from io import BytesIO
+from pathlib import Path
+from typing import List, Optional
+
+from openai import OpenAI
+from pydub import AudioSegment
+from spargear import RunnableArguments
+
+
+# -------------------------------------------------------------------
+# Helper functions for timestamp parsing & segment selection
+# -------------------------------------------------------------------
+def parse_timestamp(ts: str) -> float:
+    """
+    Parse a timestamp string into seconds.
+    Supports:
+      - "SS" or "SS.sss"
+      - "MM:SS" or "MM:SS.sss"
+      - "HH:MM:SS" or "HH:MM:SS.sss"
+    """
+    parts = ts.split(":")
+    seconds = 0.0
+    for idx, part in enumerate(reversed(parts)):
+        if not part:
+            value = 0.0
+        else:
+            value = float(part)
+        if idx == 0:
+            seconds += value
+        elif idx == 1:
+            seconds += value * 60
+        elif idx == 2:
+            seconds += value * 3600
+        else:
+            raise ValueError(f"Timestamp '{ts}' is too long (use H:MM:SS at most)")
+    return seconds
+
+
+def get_selected_audio(audio: AudioSegment, segments_str: str) -> AudioSegment:
+    """
+    Given full audio and a segments string (e.g. "650-750,16:50-17:30,800-"),
+    extract those subranges and concatenate them.
+    """
+    duration_ms = len(audio)
+    duration_s = duration_ms / 1000.0
+    subsegments: List[AudioSegment] = []
+
+    for part in segments_str.split(","):
+        if "-" not in part:
+            raise ValueError(f"Invalid segment '{part}' (must contain '-')")
+        start_str, end_str = part.split("-", 1)
+        start_s = parse_timestamp(start_str) if start_str.strip() else 0.0
+        end_s = parse_timestamp(end_str) if end_str.strip() else duration_s
+
+        # clamp
+        start_s = max(0.0, min(start_s, duration_s))
+        end_s = max(0.0, min(end_s, duration_s))
+        if end_s <= start_s:
+            print(f"[!] Warning: segment '{part}' yields non-positive duration; skipping.")
+            continue
+
+        start_ms = int(start_s * 1000)
+        end_ms = int(end_s * 1000)
+        sub = audio[start_ms:end_ms]
+        subsegments.append(sub)
+        print(f"[i] Selected segment {start_s:.2f}s–{end_s:.2f}s ({end_s - start_s:.2f}s)")
+
+    if not subsegments:
+        raise RuntimeError("No valid segments were specified.")
+    # concatenate
+    combined = subsegments[0]
+    for seg in subsegments[1:]:
+        combined += seg
+    return combined
+
+
+# -------------------------------------------------------------------
+# Main transcription logic
+# -------------------------------------------------------------------
+class Arguments(RunnableArguments[None]):
+    AUDIO_PATH: Path
+    """The audio file to transcribe."""
+    output: Optional[Path] = None
+    """Path to save the transcription output."""
+    model: str = "gpt-4o-transcribe"
+    """The model to use for transcription."""
+    api_key: Optional[str] = None
+    """The API key for authentication."""
+    base_url: str = "https://api.openai.com/v1"
+    """The base URL for the API."""
+    prompt: str = "Transcribe whole text from audio."
+    """The prompt to use for transcription."""
+    segments: Optional[str] = None
+    """
+    Comma-separated list of time ranges to include (e.g. "650-750,16:50-17:30,800-").
+    Each range is start-end; start or end may be omitted.
+    Supports seconds or H:MM:SS formats.
+    """
+    max_chunk_duration: int = 600
+    """Maximum duration of each chunk in seconds."""
+
+    def run(self) -> None:
+        client = OpenAI(api_key=self.api_key, base_url=self.base_url)
+
+        # 1) Load entire audio
+        original_audio = load_audio_segment(self.AUDIO_PATH)
+
+        # 2) If segments specified, extract & combine
+        if self.segments:
+            audio = get_selected_audio(original_audio, self.segments)
+            print(f"[i] Combined audio duration: {len(audio) / 1000:.1f}s (from segments)")
+        else:
+            audio = original_audio
+            print(f"[i] Audio duration: {len(audio) / 1000:.1f}s (full audio)")
+
+        # 3) Split into chunks
+        segments = split_audio(audio, self.max_chunk_duration)
+        print(f"[i] Splitting into {len(segments)} segment(s) for transcription")
+
+        # 4) Transcribe each chunk
+        transcripts: List[str] = []
+        for idx, seg in enumerate(segments, start=1):
+            print(f"[i] Transcribing segment {idx}/{len(segments)}...")
+            transcripts.append(transcribe_segment(seg, client, self.model, self.prompt))
+
+        # 5) Write out
+        full = "\n\n".join(transcripts)
+        out_path = self.output or self.AUDIO_PATH.with_suffix(".txt")
+        out_path.write_text(full, encoding="utf-8")
+        print(f"[✓] Transcription saved to: {out_path}")
+
+
+def load_audio_segment(file_path: Path) -> AudioSegment:
+    """
+    Load an audio file as an AudioSegment. Convert to mp3 format in-memory if needed.
+    """
+    ext = file_path.suffix.lower()[1:]
+    audio = AudioSegment.from_file(file_path.as_posix(), format=None if ext == "mp3" else ext)
+    if ext != "mp3":
+        buffer = BytesIO()
+        audio.export(buffer, format="mp3")
+        buffer.seek(0)
+        audio = AudioSegment.from_file(buffer, format="mp3")
+    return audio
+
+
+def split_audio(audio: AudioSegment, max_duration_s: int) -> List[AudioSegment]:
+    """
+    Split the AudioSegment into chunks no longer than max_duration_s seconds.
+    """
+    chunk_ms = (max_duration_s - 1) * 1000
+    duration_ms = len(audio)
+    segments: List[AudioSegment] = []
+    for start in range(0, duration_ms, chunk_ms):
+        end = min(start + chunk_ms, duration_ms)
+        segments.append(audio[start:end])
+    return segments
+
+
+def transcribe_segment(segment: AudioSegment, client: OpenAI, model: str, prompt: str) -> str:
+    """
+    Transcribe a single AudioSegment chunk and return its text.
+    """
+    buffer = BytesIO()
+    segment.export(buffer, format="mp3")
+    buffer.seek(0)
+    mp3_bytes = buffer.read()
+
+    response = client.audio.transcriptions.create(
+        model=model,
+        prompt=prompt,
+        file=("audio.mp3", mp3_bytes),
+        response_format="text",
+        stream=True,
+    )
+    for res in response:
+        if res.type == "transcript.text.delta":
+            print(res.delta, end="", flush=True)
+        elif res.type == "transcript.text.done":
+            print()
+            return res.text
+    raise RuntimeError("No transcription result found.")
+
+
+def main() -> None:
+    Arguments().run()
+
+
+if __name__ == "__main__":
+    main()

chatterer/examples/{upstage_parser.py → upstage.py}

@@ -1,89 +1,89 @@
-import logging
-from pathlib import Path
-from typing import Optional
-
-from langchain_core.documents.base import Blob
-from spargear import ArgumentSpec, BaseArguments
-
-from chatterer import Chatterer, UpstageDocumentParseParser
-from chatterer.tools.upstage_document_parser import (
-    DEFAULT_IMAGE_DIR,
-    DOCUMENT_PARSE_BASE_URL,
-    DOCUMENT_PARSE_DEFAULT_MODEL,
-    OCR,
-    Category,
-    OutputFormat,
-    SplitType,
-)
-
-logger = logging.getLogger(__name__)
-
-
-class UpstageParserArguments(BaseArguments):
-    input: Path
-    """Input file to parse. Can be a PDF, image, or other supported formats."""
-    output: Optional[Path] = None
-    """Output file path for the parsed content. Defaults to input file with .md suffix if not provided."""
-    api_key: Optional[str] = None
-    """API key for the Upstage API."""
-    base_url: str = DOCUMENT_PARSE_BASE_URL
-    """Base URL for the Upstage API."""
-    model: str = DOCUMENT_PARSE_DEFAULT_MODEL
-    """Model to use for parsing."""
-    split: SplitType = "none"
-    """Split type for the parsed content."""
-    ocr: OCR = "auto"
-    """OCR type for parsing."""
-    output_format: OutputFormat = "markdown"
-    """Output format for the parsed content."""
-    coordinates: bool = False
-    """Whether to include coordinates in the output."""
-    base64_encoding: list[Category] = ["figure"]
-    """Base64 encoding for specific categories in the parsed content."""
-    image_description_instruction: str = "Describe the image in detail."
-    """Instruction for generating image descriptions."""
-    image_dir: str = DEFAULT_IMAGE_DIR
-    """Directory to save images extracted from the document."""
-    chatterer: ArgumentSpec[Chatterer] = ArgumentSpec(
-        ["--chatterer"],
-        default=None,
-        help="Chatterer instance for communication.",
-        type=Chatterer.from_provider,
-    )
-
-    def run(self) -> None:
-        input = UpstageParserArguments.input.resolve()
-        out = UpstageParserArguments.output or input.with_suffix(".md")
-
-        parser = UpstageDocumentParseParser(
-            api_key=UpstageParserArguments.api_key,
-            base_url=UpstageParserArguments.base_url,
-            model=UpstageParserArguments.model,
-            split=UpstageParserArguments.split,
-            ocr=UpstageParserArguments.ocr,
-            output_format=UpstageParserArguments.output_format,
-            coordinates=UpstageParserArguments.coordinates,
-            base64_encoding=UpstageParserArguments.base64_encoding,
-            image_description_instruction=UpstageParserArguments.image_description_instruction,
-            image_dir=UpstageParserArguments.image_dir,
-            chatterer=UpstageParserArguments.chatterer.value,
-        )
-        docs = parser.parse(Blob.from_path(input))  # pyright: ignore[reportUnknownMemberType]
-
-        if UpstageParserArguments.image_dir:
-            for path, image in parser.image_data.items():
-                (path := Path(path)).parent.mkdir(parents=True, exist_ok=True)
-                path.write_bytes(image)
-                logger.info(f"Saved image to `{path}`")
-
-        markdown: str = "\n\n".join(f"<!--- page {i} -->\n{doc.page_content}" for i, doc in enumerate(docs, 1))
-        out.write_text(markdown, encoding="utf-8")
-        logger.info(f"Parsed `{input}` to `{out}`")
-
-
-def main() -> None:
-    UpstageParserArguments().run()
-
-
-if __name__ == "__main__":
-    main()
+import logging
+from pathlib import Path
+from typing import Optional
+
+from langchain_core.documents.base import Blob
+from spargear import ArgumentSpec, BaseArguments
+
+from chatterer import Chatterer, UpstageDocumentParseParser
+from chatterer.tools.upstage_document_parser import (
+    DEFAULT_IMAGE_DIR,
+    DOCUMENT_PARSE_BASE_URL,
+    DOCUMENT_PARSE_DEFAULT_MODEL,
+    OCR,
+    Category,
+    OutputFormat,
+    SplitType,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class Arguments(BaseArguments):
+    INPUT_PATH: Path
+    """Input file to parse. Can be a PDF, image, or other supported formats."""
+    output: Optional[Path] = None
+    """Output file path for the parsed content. Defaults to input file with .md suffix if not provided."""
+    api_key: Optional[str] = None
+    """API key for the Upstage API."""
+    base_url: str = DOCUMENT_PARSE_BASE_URL
+    """Base URL for the Upstage API."""
+    model: str = DOCUMENT_PARSE_DEFAULT_MODEL
+    """Model to use for parsing."""
+    split: SplitType = "none"
+    """Split type for the parsed content."""
+    ocr: OCR = "auto"
+    """OCR type for parsing."""
+    output_format: OutputFormat = "markdown"
+    """Output format for the parsed content."""
+    coordinates: bool = False
+    """Whether to include coordinates in the output."""
+    base64_encoding: list[Category] = ["figure"]
+    """Base64 encoding for specific categories in the parsed content."""
+    image_description_instruction: str = "Describe the image in detail."
+    """Instruction for generating image descriptions."""
+    image_dir: str = DEFAULT_IMAGE_DIR
+    """Directory to save images extracted from the document."""
+    chatterer: ArgumentSpec[Chatterer] = ArgumentSpec(
+        ["--chatterer"],
+        default=None,
+        help="Chatterer instance for communication.",
+        type=Chatterer.from_provider,
+    )
+
+    def run(self) -> None:
+        input = self.INPUT_PATH.resolve()
+        out = self.output or input.with_suffix(".md")
+
+        parser = UpstageDocumentParseParser(
+            api_key=self.api_key,
+            base_url=self.base_url,
+            model=self.model,
+            split=self.split,
+            ocr=self.ocr,
+            output_format=self.output_format,
+            coordinates=self.coordinates,
+            base64_encoding=self.base64_encoding,
+            image_description_instruction=self.image_description_instruction,
+            image_dir=self.image_dir,
+            chatterer=self.chatterer.value,
+        )
+        docs = parser.parse(Blob.from_path(input))  # pyright: ignore[reportUnknownMemberType]
+
+        if self.image_dir:
+            for path, image in parser.image_data.items():
+                (path := Path(path)).parent.mkdir(parents=True, exist_ok=True)
+                path.write_bytes(image)
+                logger.info(f"Saved image to `{path}`")
+
+        markdown: str = "\n\n".join(f"<!--- page {i} -->\n{doc.page_content}" for i, doc in enumerate(docs, 1))
+        out.write_text(markdown, encoding="utf-8")
+        logger.info(f"Parsed `{input}` to `{out}`")
+
+
+def main() -> None:
+    Arguments().run()
+
+
+if __name__ == "__main__":
+    main()