python-xli 0.2.0__tar.gz

python_xli-0.2.0/.gitignore

@@ -0,0 +1,220 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

python_xli-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xli contributors
+
+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.

python_xli-0.2.0/PKG-INFO

@@ -0,0 +1,397 @@
+Metadata-Version: 2.4
+Name: python-xli
+Version: 0.2.0
+Summary: Build polished, transcript-style terminal interfaces for chat / agent / REPL-ish apps in 20 lines of Python.
+Project-URL: Homepage, https://github.com/vitalops/xli
+Project-URL: Issues, https://github.com/vitalops/xli/issues
+Author-email: Fariz Rahman <farizrahman4u@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: agent,chat,cli,prompt-toolkit,rich,terminal,transcript,tui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Topic :: Terminals
+Requires-Python: >=3.11
+Requires-Dist: prompt-toolkit>=3.0.40
+Requires-Dist: rich>=13.7
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: images
+Requires-Dist: pillow>=10.0; extra == 'images'
+Provides-Extra: markdown
+Requires-Dist: pygments>=2.17; extra == 'markdown'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# xli
+
+**Build polished, transcript-style terminal UIs for chat, agent, and REPL apps — in ~20 lines of Python.** ✨
+
+[![PyPI](https://img.shields.io/pypi/v/xli.svg)](https://pypi.org/project/xli/)
+[![Python](https://img.shields.io/pypi/pyversions/xli.svg)](https://pypi.org/project/xli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Built on rich + prompt_toolkit](https://img.shields.io/badge/built%20on-rich%20%2B%20prompt__toolkit-8a2be2.svg)](#-credits)
+
+</div>
+
+```python
+import xli
+
+ui = xli.UI(title="echo")
+
+@ui.on_prompt
+async def reply(prompt: str) -> None:
+    with ui.streaming("assistant") as out:
+        for token in f"You said: {prompt}".split():
+            out.write(token + " ")
+
+ui.run()
+```
+
+That little snippet gets you: markdown-rendered **streaming** responses, slash-command
+autocomplete, `@file` mentions, multi-line input (Enter sends, Alt+Enter for newlines),
+persistent history, a themed status bar, arrow-selectable prompts, inline approvals — and a
+terminal that *feels right*. 🪄
+
+And the best part: the transcript flows into your terminal's **normal scrollback**, so text stays
+**selectable, scrollable, and searchable** with your terminal's own tools. xli doesn't take over
+the screen.
+
+---
+
+## ✨ Highlights
+
+- 📜 **Real scrollback, not a screen takeover.** Finalized output is printed into your terminal's
+  native scrollback — select, scroll, and find all work the way they always do.
+- 🌊 **Streaming markdown** that appears token-by-token, then settles into properly-rendered text.
+- 🃏 **Mutable cards.** A tool call flips from `running` → `done` *in place*; a plan's checkboxes
+  tick off live — via a handle you hold and update from anywhere.
+- ⌨️ **A real composer.** Multi-line input, slash-command autocomplete, `@file` mentions, history,
+  and paste handling out of the box.
+- ✅ **Inline approvals, pickers & wizards** — arrow-selectable, no modal screen-takeover, and they
+  block your agent until the user answers.
+- ⏸️ **Type-ahead & ESC-to-interrupt** while the agent is working, with cooperative `asyncio`
+  cancellation.
+- 🎨 **Themeable** via plain dataclasses — minimal/glyph-driven by default, boxed if you insist.
+- 🪶 **Tiny surface, two deps.** Wraps [rich](https://github.com/Textualize/rich) for rendering and
+  [prompt_toolkit](https://github.com/prompt-toolkit/python-prompt-toolkit) for input. No build steps.
+
+## 🤔 What it is
+
+A small, opinionated library for **one specific job**: interactive agent / chat-style terminal apps
+where output is a *flowing transcript*, not an app screen.
+
+The pattern xli handles:
+
+- A scrolling transcript of structured cards — user messages, assistant messages, tool calls,
+  diffs, plans, reasoning, images — committed to real scrollback.
+- Streaming markdown that appears as it arrives, then settles into rendered scrollback.
+- A persistent multi-line composer at the bottom with autocomplete, `@file` mentions, and history.
+- **Mutable cards** — a tool card that flips `running` → `done` in place, a plan whose checkboxes
+  update — via a handle you hold.
+- Inline, arrow-selectable approvals / pickers / wizards that block until resolved.
+- A subtle status bar, an animated "working" spinner, type-ahead, and ESC-to-interrupt.
+
+## 🚫 What it is NOT
+
+| Not… | Because |
+|---|---|
+| A TUI framework | No widget tree, no CSS, no focus model, no mouse panes. Reach for [Textual](https://github.com/Textualize/textual) when you want a full app screen. |
+| A "richer `print`" | xli is interactive — it owns the event loop. For one-shot static rendering, use [rich](https://github.com/Textualize/rich) directly. |
+| A full-screen app | It renders **inline** so your terminal keeps native scroll / select / find. That's the whole point. |
+| Tied to any LLM / agent framework | It knows nothing about providers. It renders the events *you* emit — OpenAI, Anthropic, LangChain, your own loop, whatever. |
+| A REPL builder | It runs *your* code in response to prompts. For a Python REPL, use [ptpython](https://github.com/prompt-toolkit/ptpython). |
+
+## ⚖️ How it compares
+
+xli lives in the gap between "low-level rendering toolkit" and "full-screen app framework." If your
+output is a **conversation that scrolls**, that gap is exactly where you want to be.
+
+| | xli | [Textual](https://github.com/Textualize/textual) | [rich](https://github.com/Textualize/rich) | [prompt_toolkit](https://github.com/prompt-toolkit/python-prompt-toolkit) | [questionary](https://github.com/tmbo/questionary) |
+|---|---|---|---|---|---|
+| **Shape** | Flowing transcript | Full-screen app | Print / render | Input / REPL | Prompts only |
+| **Native scrollback** | ✅ keeps it | ❌ takes over screen | ✅ (it just prints) | ⚠️ partial | ✅ |
+| **Streaming + mutable cards** | ✅ built-in | ✅ (you wire widgets) | ❌ DIY | ❌ DIY | ❌ |
+| **Composer (multiline, history, `@`, `/`)** | ✅ built-in | 🔧 build from widgets | ❌ | 🔧 primitives | ❌ |
+| **Inline approvals / pickers / wizards** | ✅ built-in | 🔧 build from widgets | ❌ | 🔧 primitives | ✅ (pickers) |
+| **Best for** | Chat / agent transcripts | Dashboards, IDEs, full apps | Static output | Custom REPLs & input | One-off questionnaires |
+
+**In short:** Textual gives you a canvas to build *any* app and asks you to design the whole screen.
+xli gives you *one* app shape — the agent/chat transcript — already assembled, and hands the
+scrollback back to your terminal. If you've been gluing rich + prompt_toolkit together to make a
+chat loop, xli *is* that glue, done well. 🙂
+
+## 📦 Install
+
+```sh
+pip install xli
+```
+
+Optional extras:
+
+- `xli[markdown]` — `pygments` for code-block syntax highlighting in messages (recommended).
+- `xli[images]` — `pillow`, for inline images (`ui.image(...)`).
+
+Two core dependencies (rich, prompt_toolkit). No build steps. Requires Python **3.11+**.
+
+## 🚀 Quickstart
+
+A fuller echo agent — streaming, a status field, a tool card that updates in place, and a slash
+command:
+
+```python
+import asyncio
+import xli
+
+ui = xli.UI(title="echo", status_fields=["turn"], pet="cat")
+turn = 0
+
+@ui.command("clear", description="clear the screen")
+async def clear(ui, args):
+    ui.clear_transcript()
+
+@ui.on_prompt
+async def handle(prompt: str) -> None:
+    global turn
+    turn += 1
+    ui.status.set(turn=turn)
+
+    card = ui.tool("think", status="running")        # live, mutable card
+    with ui.working("thinking"):
+        await asyncio.sleep(0.5)
+    card.update(status="done", output="ok")          # commits to scrollback
+
+    with ui.streaming("assistant") as out:
+        for token in f"You said: **{prompt}**".split():
+            out.write(token + " ")
+            await asyncio.sleep(0.04)
+
+ui.run()
+```
+
+> 💡 Want to see everything at once? `examples/demo.py` exercises every feature in one file.
+
+## 📖 The vocabulary
+
+`xli.UI` exposes a small set of methods you call from any handler. Transcript methods return a
+**cell handle** you can mutate.
+
+```python
+# --- streaming + cards (return a Cell handle) ---
+with ui.streaming(role) as out:   # streamed text; out.write(chunk); out.text
+    ...
+card = ui.tool(name, args=, output=, status="running")  # status="running" -> live + mutable
+card.update(status="done", output=...)                  # mutate in place; commits when final
+card.remove()                                           # drop a live cell
+
+ui.message(role, text)            # one-shot message
+ui.diff(diff, path=)              # syntax-colored unified diff
+ui.plan([("step", "status"), …])  # checklist
+ui.reasoning(summary)             # muted thought rail
+ui.image("plot.png")              # inline image (kitty / iTerm2 / half-block fallback)
+ui.link("label", "https://…")     # OSC 8 hyperlink
+ui.note("…") / ui.header("…")     # muted status lines
+ui.print(any_rich_renderable)     # escape hatch for custom rendering
+
+# --- a spinner while you work ---
+with ui.working("running tests"): ...     # animated, with an elapsed timer
+
+# --- blocking prompts (await) ---
+decision = await ui.approve(title=, body=, reason=)   # arrow-select Yes / Always / No
+choice   = await ui.pick("Model", ["gpt-5", "claude-opus"])   # ↑/↓ · 1-9 · enter
+yes      = await ui.confirm("Delete?")
+name     = await ui.input("Name?", default="")
+answers  = await ui.wizard([                          # multi-step flow -> dict
+    ui.step.pick("Model", ["opus", "sonnet"]),
+    ui.step.confirm("Stream responses?"),
+    ui.step.text("Project name", default="app"),
+])
+
+# --- chrome + lifecycle ---
+ui.status.set(model="gpt-5", tokens="3.2k/400k")   # bottom bar (declare fields up front)
+ui.notify("response ready")                         # desktop notification (OSC 9)
+ui.clear_transcript()
+ui.exit()
+```
+
+## 🧠 The one design decision
+
+xli renders **inline**, not full-screen. Finalized cells are *printed into your terminal's normal
+scrollback* — so selection, scrolling, and find all come from the terminal itself. Only a small
+**live region** at the bottom (the composer, status bar, an in-progress stream, a running tool
+card, a spinner, a picker) is redrawn.
+
+A cell is **mutable while it's live** at the bottom; once it finalizes it **commits to scrollback**
+and becomes immutable (but selectable). That two-tier model is what lets xli have both editable,
+animated cards *and* native, selectable scrollback — the thing full-screen TUIs give up.
+
+## 🃏 Mutable cards
+
+The transcript methods return a handle. Hold it, mutate it from anywhere (including across `await`s
+and from other tasks) — it re-renders in place while live, then commits to scrollback once it's
+finalized:
+
+```python
+card = ui.tool("shell", status="running", args={"command": ["pytest", "-q"]})
+result = await run_shell(...)
+card.update(status="done", output=result)        # ✓ shell … and the output, committed
+```
+
+A `ui.tool(...)` **without** a `status` is a one-shot card (committed immediately). With
+`status="running"` it stays live and mutable until you update it to `done` / `error` / `cancelled`.
+
+## ⌨️ Slash commands & @file mentions
+
+```python
+@ui.command("model", description="switch model")
+async def cmd_model(ui, args):
+    sel = await ui.pick("Model", ["gpt-5", "claude-opus"])
+    if sel is not None:
+        ui.status.set(model=sel)
+
+@ui.command("quit", aliases=["q", "exit"])
+async def cmd_quit(ui, args):
+    ui.exit()
+```
+
+Typing `/` opens a command list **below** the composer (arrow to navigate, Tab to fill, Enter to
+run). `/help`, `/quit`, and `/clear` are built in (override freely). Typing `@` opens a **file
+picker** from the working directory; Tab/Enter inserts the path — handy for letting users reference
+files for your agent.
+
+## ✅ Approvals, pickers, wizards
+
+All are inline and arrow-selectable (no modal screen-takeover). The request commits to scrollback so
+it scrolls into view and persists; the choices appear in the live region; the outcome is recorded
+below.
+
+```python
+decision = await ui.approve(
+    title="apply patch to README.md",
+    body="add a one-liner about xli",
+    reason="writes outside the workspace root",
+)   # -> "approved" | "approved_for_session" | "denied" | "aborted"
+```
+
+`↑/↓` move the highlight, `1`-`9` quick-select, `Enter` confirms, `Esc` cancels.
+
+## ⏸️ Interrupts
+
+The composer stays live while your handler runs — users can **type ahead** (queued prompts show as
+muted `⋯` lines) and press **ESC to interrupt** the current turn. Interrupt is cooperative `asyncio`
+cancellation; register cleanup with `@ui.on_interrupt`:
+
+```python
+@ui.on_interrupt
+async def cleanup():
+    await release_resources()       # don't write to the transcript here
+```
+
+A running tool card left behind by an interrupted turn is automatically marked `cancelled`.
+
+## 🎨 Themes
+
+```python
+ui = xli.UI(theme="codex")        # default — minimal, glyph-driven, no borders, no solid bg
+ui = xli.UI(theme="minimal")      # even more austere
+ui = xli.UI(theme="boxed")        # rounded borders if you really want them
+ui = xli.UI(theme=xli.Theme(      # custom — it's a dataclass; override fields
+    user_color="cyan",
+    tool_glyph="→",
+    code_theme="monokai",
+))
+```
+
+Themes are dataclasses — override fields, don't subclass. The default leans "light": chrome is font
+color + thin rules, never solid background blocks. See [`docs/theme.md`](docs/theme.md) for the
+design guide you can hand to a coding agent.
+
+## 🔌 Plugging into an agent
+
+xli renders the event types you give it. It doesn't care if those come from OpenAI, Anthropic,
+LangChain, or your own framework:
+
+```python
+@ui.on_prompt
+async def handle(prompt: str) -> None:
+    cards = {}                                        # tool-call id -> live card handle
+    async for event in my_agent.stream(prompt):
+        if event.kind == "message":
+            ui.message("assistant", event.text)
+        elif event.kind == "tool_call":
+            cards[event.id] = ui.tool(event.name, args=event.args, status="running")
+        elif event.kind == "tool_result":
+            cards[event.id].update(status="done", output=event.output)   # flips in place
+        elif event.kind == "approval_request":
+            decision = await ui.approve(title=event.title, body=event.body)
+            my_agent.respond(event.id, decision)
+```
+
+For token-by-token output, wrap a `with ui.streaming("assistant") as out:` block and call
+`out.write(delta)` as deltas arrive. Have your own event stream? Register a custom renderer:
+
+```python
+@ui.renderer("benchmark")
+def render_benchmark(ui, event):
+    ui.print(make_bar_chart(event["data"]))
+
+ui.dispatch({"type": "benchmark", "data": [...]})
+```
+
+## ⌨️ Keys
+
+```
+enter                send  (or run highlighted command / select picker option / accept input)
+alt+enter ⋅ ctrl+j   newline
+↑ / ↓                history · navigate the command/file list · move picker selection
+tab                  accept the highlighted completion / insert @file path
+1–9                  quick-select a picker option
+esc                  cancel a picker/modal or close the list — otherwise interrupt the turn
+ctrl+c               interrupt          ctrl+d  quit
+```
+
+## 🛠️ Contributing
+
+Contributions, bug reports, and ideas are very welcome! 🙌
+
+```sh
+git clone https://github.com/fariz/xli
+cd xli
+pip install -e ".[dev,markdown,images]"
+pytest            # run the tests
+ruff check .      # lint
+mypy xli          # type-check
+```
+
+Found a rough edge or have a use case xli doesn't cover cleanly? Open an
+[issue](https://github.com/fariz/xli/issues) — the API is small on purpose, so design
+conversations matter.
+
+## 📍 Status
+
+**Pre-1.0** (currently `0.2.0`). The API is stable enough to build on; versions are bumped
+thoughtfully if anything user-facing changes.
+
+## 🙏 Credits
+
+xli stands on the shoulders of two excellent libraries:
+
+- [**rich**](https://github.com/Textualize/rich) — all the rendering.
+- [**prompt_toolkit**](https://github.com/prompt-toolkit/python-prompt-toolkit) — all the input.
+
+xli's contribution is the *composition*: the API you'd actually want to write a chat/agent terminal
+app in.
+
+## 📄 License
+
+[MIT](LICENSE) © xli contributors