puenteo 0.4.0__tar.gz

puenteo-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mano7onam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

puenteo-0.4.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: puenteo
+Version: 0.4.0
+Summary: Puenteo — the bridge between coding agents. List, search, and export Claude/Codex/Grok/Pi sessions to md/html/pdf/json/zip (Python library + CLI).
+Author-email: mano7onam <mano7onamm@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/mano7onam/puenteo
+Project-URL: Repository, https://github.com/mano7onam/puenteo
+Project-URL: Issues, https://github.com/mano7onam/puenteo/issues
+Project-URL: Changelog, https://github.com/mano7onam/puenteo/releases
+Keywords: agents,bridge,puente,claude-code,codex,grok,cli,library,export,markdown,pdf,session,developer-tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# puenteo
+
+**The bridge between coding agents.**
+
+Python **library + CLI** to discover, search, and export local sessions from Claude Code, Codex, Grok, and Pi — to Markdown, HTML, PDF, JSON, ZIP, CSV, XML, YAML.
+
+*Puenteo* ← Spanish *puente* (bridge) + *puentear* (to bridge / jump across).
+
+Zero runtime dependencies · Python ≥ 3.9
+
+[![PyPI](https://img.shields.io/pypi/v/puenteo.svg)](https://pypi.org/project/puenteo/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+## Install
+
+```bash
+pip install puenteo
+# or
+uv add puenteo
+# or
+pipx install puenteo
+```
+
+From source:
+
+```bash
+git clone https://github.com/mano7onam/puenteo.git
+cd puenteo
+python3 -m venv .venv && .venv/bin/pip install -e .
+```
+
+## Library
+
+```python
+import puenteo
+
+print(puenteo.status())
+
+for s in puenteo.list_sessions(limit=10):
+    print(s.provider, s.session_id[:8], s.title)
+
+t = puenteo.load("019f7a24", include_tools=True)
+hits = puenteo.search("gatekeeper dmg")
+msgs = puenteo.pull("019f7a24", query="export", mode="query")
+
+puenteo.export_session("019f7a24", fmt="md", output="chat.md")
+puenteo.export_session("019f7a24", fmt="pdf", output="chat.pdf")
+puenteo.export_session("019f7a24", fmt="all", output="./exports/")
+
+data, media_type, filename = puenteo.export_bytes("019f7a24", fmt="html")
+```
+
+## CLI
+
+```bash
+puenteo status
+puenteo list -n 20 --json
+puenteo list --provider claude,grok --cwd ~/dev/myapp
+puenteo show <id> --last 40
+puenteo search "topic" --json
+puenteo pull <id> --query "topic" --mode query --max-chars 8000
+puenteo export <id> -f md -o chat.md
+puenteo export <id> -f pdf -o chat.pdf
+puenteo export <id> -f html|json|zip|csv|xml|yaml -o …
+puenteo export <id> -f all -o ./out/
+```
+
+Short alias after install: `pto` (same as `puenteo`).
+
+`<id>` = full uuid, **prefix**, path, or unique title substring.
+
+## Providers
+
+| Provider | Store |
+|----------|--------|
+| Claude Code | `~/.claude/projects/**/*.jsonl` |
+| Codex | `~/.codex/sessions/**/rollout-*.jsonl` |
+| Grok | `~/.grok/sessions/**/chat_history.jsonl` |
+| Pi | `~/.pi/agent/sessions/**/*.jsonl` |
+
+## Export formats
+
+`md` · `txt` · `html` · `pdf` · `json` · `zip` · `csv` · `xml` · `yaml`
+
+## Agent skill
+
+```bash
+./scripts/install_skills.sh
+```
+
+## Used by
+
+[Terminal Dashboard](https://github.com/mano7onam/terminal-dashboard) imports **puenteo** for chat export (shared parsers, no duplication).
+
+## License
+
+MIT · [mano7onam/puenteo](https://github.com/mano7onam/puenteo)

puenteo-0.4.0/README.md

@@ -0,0 +1,97 @@
+# puenteo
+
+**The bridge between coding agents.**
+
+Python **library + CLI** to discover, search, and export local sessions from Claude Code, Codex, Grok, and Pi — to Markdown, HTML, PDF, JSON, ZIP, CSV, XML, YAML.
+
+*Puenteo* ← Spanish *puente* (bridge) + *puentear* (to bridge / jump across).
+
+Zero runtime dependencies · Python ≥ 3.9
+
+[![PyPI](https://img.shields.io/pypi/v/puenteo.svg)](https://pypi.org/project/puenteo/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+## Install
+
+```bash
+pip install puenteo
+# or
+uv add puenteo
+# or
+pipx install puenteo
+```
+
+From source:
+
+```bash
+git clone https://github.com/mano7onam/puenteo.git
+cd puenteo
+python3 -m venv .venv && .venv/bin/pip install -e .
+```
+
+## Library
+
+```python
+import puenteo
+
+print(puenteo.status())
+
+for s in puenteo.list_sessions(limit=10):
+    print(s.provider, s.session_id[:8], s.title)
+
+t = puenteo.load("019f7a24", include_tools=True)
+hits = puenteo.search("gatekeeper dmg")
+msgs = puenteo.pull("019f7a24", query="export", mode="query")
+
+puenteo.export_session("019f7a24", fmt="md", output="chat.md")
+puenteo.export_session("019f7a24", fmt="pdf", output="chat.pdf")
+puenteo.export_session("019f7a24", fmt="all", output="./exports/")
+
+data, media_type, filename = puenteo.export_bytes("019f7a24", fmt="html")
+```
+
+## CLI
+
+```bash
+puenteo status
+puenteo list -n 20 --json
+puenteo list --provider claude,grok --cwd ~/dev/myapp
+puenteo show <id> --last 40
+puenteo search "topic" --json
+puenteo pull <id> --query "topic" --mode query --max-chars 8000
+puenteo export <id> -f md -o chat.md
+puenteo export <id> -f pdf -o chat.pdf
+puenteo export <id> -f html|json|zip|csv|xml|yaml -o …
+puenteo export <id> -f all -o ./out/
+```
+
+Short alias after install: `pto` (same as `puenteo`).
+
+`<id>` = full uuid, **prefix**, path, or unique title substring.
+
+## Providers
+
+| Provider | Store |
+|----------|--------|
+| Claude Code | `~/.claude/projects/**/*.jsonl` |
+| Codex | `~/.codex/sessions/**/rollout-*.jsonl` |
+| Grok | `~/.grok/sessions/**/chat_history.jsonl` |
+| Pi | `~/.pi/agent/sessions/**/*.jsonl` |
+
+## Export formats
+
+`md` · `txt` · `html` · `pdf` · `json` · `zip` · `csv` · `xml` · `yaml`
+
+## Agent skill
+
+```bash
+./scripts/install_skills.sh
+```
+
+## Used by
+
+[Terminal Dashboard](https://github.com/mano7onam/terminal-dashboard) imports **puenteo** for chat export (shared parsers, no duplication).
+
+## License
+
+MIT · [mano7onam/puenteo](https://github.com/mano7onam/puenteo)

puenteo-0.4.0/puenteo/__init__.py

@@ -0,0 +1,89 @@
+"""
+Puenteo — the bridge between coding agents.
+
+Install::
+
+    pip install puenteo
+    # CLI:
+    puenteo list
+    puenteo export <session_id> -f md -o chat.md
+
+Library::
+
+    import puenteo
+
+    print(puenteo.status())
+    for s in puenteo.list_sessions(limit=10):
+        print(s.provider, s.session_id[:8], s.title)
+
+    puenteo.export_session("019f7a24", fmt="pdf", output="chat.pdf")
+    hits = puenteo.search("export markdown")
+    msgs = puenteo.pull("019f7a24", query="dmg", mode="query")
+
+Providers: Claude Code, Codex, Grok, Pi.
+Formats: md, txt, html, pdf, json, zip, csv, xml, yaml.
+"""
+
+from .api import (  # noqa: F401
+    APP_NAME,
+    SUPPORTED_FORMATS,
+    Attachment,
+    Hit,
+    Message,
+    PROVIDER_NAMES,
+    RichMessage,
+    RichTranscript,
+    Session,
+    Transcript,
+    clipboard_text,
+    export_bytes,
+    export_session,
+    find_best_agent_transcript,
+    get_session,
+    list_sessions,
+    list_sources_for_cwd,
+    load,
+    load_rich_transcript,
+    load_transcript,
+    pull,
+    render,
+    resolve_session,
+    search,
+    search_all,
+    search_transcript,
+    smart_pull,
+    status,
+)
+from .version import __version__
+
+__all__ = [
+    "APP_NAME",
+    "SUPPORTED_FORMATS",
+    "Attachment",
+    "Hit",
+    "Message",
+    "PROVIDER_NAMES",
+    "RichMessage",
+    "RichTranscript",
+    "Session",
+    "Transcript",
+    "__version__",
+    "clipboard_text",
+    "export_bytes",
+    "export_session",
+    "find_best_agent_transcript",
+    "get_session",
+    "list_sessions",
+    "list_sources_for_cwd",
+    "load",
+    "load_rich_transcript",
+    "load_transcript",
+    "pull",
+    "render",
+    "resolve_session",
+    "search",
+    "search_all",
+    "search_transcript",
+    "smart_pull",
+    "status",
+]

puenteo-0.4.0/puenteo/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

puenteo-0.4.0/puenteo/api.py

@@ -0,0 +1,286 @@
+"""
+Public library API for Puenteo.
+
+Prefer importing from the package root::
+
+    import puenteo
+
+    sessions = puenteo.list_sessions(limit=20)
+    path = puenteo.export_session(sessions[0].session_id, fmt="md", output="chat.md")
+    hits = puenteo.search("gatekeeper")
+    pack = puenteo.pull(sessions[0].session_id, query="dmg", mode="query")
+
+CLI is the same package: ``puenteo`` / ``pto`` / ``python -m puenteo``.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence, Union
+
+from .exporters import SUPPORTED_FORMATS, clipboard_text, render
+from .extract import smart_pull
+from .models import Message, Session, Transcript
+from .providers import PROVIDER_NAMES, list_sessions, load_transcript, resolve_session
+from .rich import (
+    find_best_agent_transcript,
+    list_sources_for_cwd,
+    load_transcript as load_rich_transcript,
+)
+from .search import Hit, search_all, search_transcript
+from .version import APP_NAME, __version__
+
+# Re-export rich models for export consumers (Terminal Dashboard, etc.)
+from .rich import Attachment, Message as RichMessage, Transcript as RichTranscript
+
+
+def status() -> Dict[str, Any]:
+    """Discover which agent stores exist and how many sessions each has."""
+    from pathlib import Path as P
+
+    homes = {
+        "claude_code": P.home() / ".claude" / "projects",
+        "codex": P.home() / ".codex" / "sessions",
+        "grok": P.home() / ".grok" / "sessions",
+        "pi": P.home() / ".pi" / "agent" / "sessions",
+    }
+    providers: Dict[str, Any] = {}
+    for name, path in homes.items():
+        exists = path.is_dir()
+        count = 0
+        if exists:
+            try:
+                count = len(list_sessions(providers=[name], limit=500))
+            except Exception:
+                count = 0
+        providers[name] = {
+            "path": str(path),
+            "exists": exists,
+            "sessions": count,
+        }
+    return {
+        "name": APP_NAME,
+        "version": __version__,
+        "role": "library+cli",
+        "providers": providers,
+        "export_formats": list(SUPPORTED_FORMATS),
+        "provider_names": list(PROVIDER_NAMES),
+    }
+
+
+def get_session(
+    ref: str,
+    *,
+    providers: Optional[Sequence[str]] = None,
+    cwd: Optional[str] = None,
+) -> Optional[Session]:
+    """Resolve a session by id prefix, path, or title substring."""
+    prov = list(providers) if providers else None
+    return resolve_session(ref, providers=prov, cwd=cwd)
+
+
+def load(
+    ref: Union[str, Session],
+    *,
+    rich: bool = True,
+    include_tools: bool = False,
+    include_thinking: bool = False,
+    providers: Optional[Sequence[str]] = None,
+    cwd: Optional[str] = None,
+) -> Union[Transcript, RichTranscript]:
+    """
+    Load a session transcript.
+
+    - ``rich=True`` (default): full export model (tools, attachments) via ``rich`` loaders
+    - ``rich=False``: lightweight messages for search / pull
+    """
+    sess = ref if isinstance(ref, Session) else get_session(ref, providers=providers, cwd=cwd)
+    if not sess:
+        raise LookupError(f"Session not found: {ref!r}")
+    if rich:
+        return load_rich_transcript(
+            sess.provider,
+            sess.path,
+            include_tools=include_tools,
+            include_thinking=include_thinking,
+        )
+    return load_transcript(sess, include_tools=include_tools)
+
+
+def search(
+    query: str,
+    *,
+    session: Optional[str] = None,
+    providers: Optional[Sequence[str]] = None,
+    cwd: Optional[str] = None,
+    limit: int = 20,
+    session_limit: int = 40,
+) -> List[Hit]:
+    """Search message text across sessions (or one session)."""
+    prov = list(providers) if providers else None
+    if session:
+        sess = get_session(session, providers=prov, cwd=cwd)
+        if not sess:
+            return []
+        tr = load_transcript(sess)
+        return search_transcript(tr, query, limit=limit)
+    return search_all(
+        query,
+        providers=prov,
+        cwd=cwd,
+        session_limit=session_limit,
+        hit_limit=limit,
+    )
+
+
+def pull(
+    ref: Union[str, Session],
+    *,
+    query: Optional[str] = None,
+    mode: str = "auto",
+    last: int = 0,
+    max_chars: int = 12000,
+    max_messages: int = 30,
+    include_tools: bool = False,
+    providers: Optional[Sequence[str]] = None,
+    cwd: Optional[str] = None,
+) -> List[Message]:
+    """Build a compact message pack for another agent (same as ``puenteo pull``)."""
+    sess = ref if isinstance(ref, Session) else get_session(ref, providers=providers, cwd=cwd)
+    if not sess:
+        raise LookupError(f"Session not found: {ref!r}")
+    tr = load_transcript(sess, include_tools=include_tools)
+    return smart_pull(
+        tr,
+        query=query,
+        mode=mode,
+        last=last,
+        max_chars=max_chars,
+        max_messages=max_messages,
+    )
+
+
+def export_session(
+    ref: Union[str, Session],
+    *,
+    fmt: str = "md",
+    output: Optional[Union[str, Path]] = None,
+    include_tools: bool = False,
+    include_thinking: bool = False,
+    providers: Optional[Sequence[str]] = None,
+    cwd: Optional[str] = None,
+) -> Path:
+    """
+    Export a full transcript to a file.
+
+    ``fmt``: md | txt | html | pdf | json | zip | csv | xml | yaml | all
+
+    Returns the primary written path (or directory when ``fmt=all``).
+    """
+    sess = ref if isinstance(ref, Session) else get_session(ref, providers=providers, cwd=cwd)
+    if not sess:
+        raise LookupError(f"Session not found: {ref!r}")
+
+    rich_tr = load_rich_transcript(
+        sess.provider,
+        sess.path,
+        include_tools=include_tools,
+        include_thinking=include_thinking,
+    )
+
+    fmt_arg = (fmt or "md").lower().strip()
+    formats = list(SUPPORTED_FORMATS) if fmt_arg == "all" else [fmt_arg]
+    out = Path(os.path.expanduser(str(output))).resolve() if output else None
+
+    written: List[Path] = []
+    for f in formats:
+        data, _media, filename = render(
+            rich_tr,
+            f,
+            include_tools=include_tools,
+            include_thinking=include_thinking,
+        )
+        if out is None:
+            path = Path.cwd() / filename
+        elif out.is_dir() or fmt_arg == "all" or (out.suffix == "" and len(formats) > 1):
+            out.mkdir(parents=True, exist_ok=True)
+            path = out / filename if out.is_dir() or out.suffix == "" else out
+            if out.suffix == "" and not out.is_dir():
+                # treat as directory path to create
+                out.mkdir(parents=True, exist_ok=True)
+                path = out / filename
+        else:
+            path = out
+            path.parent.mkdir(parents=True, exist_ok=True)
+
+        path.write_bytes(data)
+        written.append(path)
+
+    if not written:
+        raise RuntimeError("Nothing exported")
+    return written[0] if len(written) == 1 else (out if out and out.is_dir() else written[0].parent)
+
+
+def export_bytes(
+    ref: Union[str, Session],
+    *,
+    fmt: str = "md",
+    include_tools: bool = False,
+    include_thinking: bool = False,
+    providers: Optional[Sequence[str]] = None,
+    cwd: Optional[str] = None,
+) -> tuple:
+    """
+    Export without writing a file.
+
+    Returns ``(data: bytes, media_type: str, filename: str)``.
+    """
+    sess = ref if isinstance(ref, Session) else get_session(ref, providers=providers, cwd=cwd)
+    if not sess:
+        raise LookupError(f"Session not found: {ref!r}")
+    rich_tr = load_rich_transcript(
+        sess.provider,
+        sess.path,
+        include_tools=include_tools,
+        include_thinking=include_thinking,
+    )
+    return render(
+        rich_tr,
+        fmt,
+        include_tools=include_tools,
+        include_thinking=include_thinking,
+    )
+
+
+__all__ = [
+    "APP_NAME",
+    "SUPPORTED_FORMATS",
+    "Attachment",
+    "Hit",
+    "Message",
+    "PROVIDER_NAMES",
+    "RichMessage",
+    "RichTranscript",
+    "Session",
+    "Transcript",
+    "__version__",
+    "clipboard_text",
+    "export_bytes",
+    "export_session",
+    "find_best_agent_transcript",
+    "get_session",
+    "list_sessions",
+    "list_sources_for_cwd",
+    "load",
+    "load_rich_transcript",
+    "load_transcript",
+    "pull",
+    "render",
+    "resolve_session",
+    "search",
+    "search_all",
+    "search_transcript",
+    "smart_pull",
+    "status",
+]