oshell 0.1.1__py3-none-any.whl

oshell/tools.py

@@ -0,0 +1,150 @@
+"""Tools the coding agent can invoke.
+
+Every tool is sandboxed to a *workspace root*: paths are resolved and must
+stay inside that root, so the agent cannot read or clobber files elsewhere
+on the machine. Mutating tools (``write_file``, ``run_command``) go through
+an approval callback so the user stays in control.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Dict
+
+# A callback the agent uses to ask the user before a risky action.
+# Receives a human-readable description and returns True to proceed.
+ApprovalFn = Callable[[str, str], bool]
+
+MAX_READ_BYTES = 100_000
+COMMAND_TIMEOUT = 120  # seconds
+
+
+@dataclass
+class ToolResult:
+    """Outcome of running a tool, fed back to the model as an observation."""
+
+    ok: bool
+    output: str
+
+    def render(self) -> str:
+        status = "OK" if self.ok else "ERROR"
+        return f"[{status}] {self.output}"
+
+
+class Toolbox:
+    """Holds the workspace root and exposes the agent's tools."""
+
+    def __init__(self, root: Path, approve: ApprovalFn, auto_approve: bool = False):
+        self.root = root.resolve()
+        self.approve = approve
+        self.auto_approve = auto_approve
+
+    # ----- path safety ---------------------------------------------------
+    def _resolve(self, rel: str) -> Path:
+        """Resolve ``rel`` inside the workspace, rejecting escapes."""
+        target = (self.root / rel).resolve()
+        if target != self.root and self.root not in target.parents:
+            raise ValueError(
+                f"Path '{rel}' is outside the workspace root and is not allowed."
+            )
+        return target
+
+    def _confirm(self, summary: str, detail: str) -> bool:
+        if self.auto_approve:
+            return True
+        return self.approve(summary, detail)
+
+    # ----- tools ---------------------------------------------------------
+    def read_file(self, path: str) -> ToolResult:
+        try:
+            target = self._resolve(path)
+        except ValueError as exc:
+            return ToolResult(False, str(exc))
+        if not target.is_file():
+            return ToolResult(False, f"File not found: {path}")
+        data = target.read_bytes()[:MAX_READ_BYTES]
+        text = data.decode("utf-8", errors="replace")
+        return ToolResult(True, text)
+
+    def write_file(self, path: str, content: str) -> ToolResult:
+        try:
+            target = self._resolve(path)
+        except ValueError as exc:
+            return ToolResult(False, str(exc))
+
+        action = "Overwrite" if target.exists() else "Create"
+        preview = content if len(content) < 800 else content[:800] + "\n… (truncated)"
+        if not self._confirm(
+            f"{action} file: {path}",
+            preview,
+        ):
+            return ToolResult(False, f"User declined to write '{path}'.")
+
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(content, encoding="utf-8")
+        return ToolResult(True, f"Wrote {len(content)} chars to {path}.")
+
+    def list_dir(self, path: str = ".") -> ToolResult:
+        try:
+            target = self._resolve(path)
+        except ValueError as exc:
+            return ToolResult(False, str(exc))
+        if not target.is_dir():
+            return ToolResult(False, f"Not a directory: {path}")
+        entries = []
+        for child in sorted(target.iterdir()):
+            mark = "/" if child.is_dir() else ""
+            entries.append(child.name + mark)
+        listing = "\n".join(entries) if entries else "(empty)"
+        return ToolResult(True, listing)
+
+    def run_command(self, command: str) -> ToolResult:
+        if not self._confirm("Run shell command", command):
+            return ToolResult(False, f"User declined to run: {command}")
+        try:
+            proc = subprocess.run(
+                command,
+                shell=True,
+                cwd=str(self.root),
+                capture_output=True,
+                text=True,
+                timeout=COMMAND_TIMEOUT,
+            )
+        except subprocess.TimeoutExpired:
+            return ToolResult(False, f"Command timed out after {COMMAND_TIMEOUT}s.")
+        out = (proc.stdout or "") + (proc.stderr or "")
+        out = out.strip() or "(no output)"
+        if len(out) > MAX_READ_BYTES:
+            out = out[:MAX_READ_BYTES] + "\n… (truncated)"
+        return ToolResult(proc.returncode == 0, f"exit={proc.returncode}\n{out}")
+
+    # ----- dispatch ------------------------------------------------------
+    def dispatch(self, action: str, args: Dict) -> ToolResult:
+        """Run a named tool with the given args dict."""
+        handlers = {
+            "read_file": lambda a: self.read_file(a.get("path", "")),
+            "write_file": lambda a: self.write_file(
+                a.get("path", ""), a.get("content", "")
+            ),
+            "list_dir": lambda a: self.list_dir(a.get("path", ".")),
+            "run_command": lambda a: self.run_command(a.get("command", "")),
+        }
+        handler = handlers.get(action)
+        if handler is None:
+            return ToolResult(False, f"Unknown action: {action!r}")
+        try:
+            return handler(args or {})
+        except Exception as exc:  # noqa: BLE001 - report tool failures to the model
+            return ToolResult(False, f"Tool raised: {exc}")
+
+
+TOOL_REFERENCE = """\
+Available tools (use exactly these action names):
+- read_file   args: {"path": "relative/path"}            -> returns file contents
+- write_file  args: {"path": "relative/path", "content": "..."} -> creates/overwrites a file
+- list_dir    args: {"path": "relative/dir"}             -> lists directory entries
+- run_command args: {"command": "shell command"}         -> runs a command in the workspace
+- finish      args: {"summary": "what you accomplished"} -> ends the task
+"""

oshell-0.1.1.dist-info/METADATA

@@ -0,0 +1,286 @@
+Metadata-Version: 2.4
+Name: oshell
+Version: 0.1.1
+Summary: A fast, beautiful terminal chat for any LLM — OpenAI or local Ollama. Zero config.
+Project-URL: Homepage, https://github.com/djaferiurim/oshell
+Project-URL: Issues, https://github.com/djaferiurim/oshell/issues
+Author: djaferiurim
+License: MIT
+License-File: LICENSE
+Keywords: ai,chat,chatgpt,cli,llm,ollama,openai,terminal
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# 🐚 oshell
+
+### Chat with any LLM, right from your terminal. Local or cloud. Zero config.
+
+[![PyPI](https://img.shields.io/badge/pip-oshell-blue)](https://pypi.org/project/oshell/)
+[![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![CI](https://github.com/djaferiurim/oshell/actions/workflows/ci.yml/badge.svg)](https://github.com/djaferiurim/oshell/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#contributing)
+
+**One command. Streaming answers. Markdown rendering. Pipe-friendly. Works offline with [Ollama](https://ollama.com) or online with OpenAI.**
+
+![oshell demo](demo.gif)
+
+</div>
+
+---
+
+```bash
+$ ai "explain monads like I'm five"
+```
+
+> A monad is like a **box** 📦 you put a value in. The box knows how to
+> open itself, do something with the value, and put the result back —
+> so you never have to unwrap it by hand…
+
+*(answer streams in live, rendered as Markdown)*
+
+---
+
+## ✨ Why oshell?
+
+- 🚀 **Instant** — ask a question without leaving your shell
+- 🤖 **Coding agent** — it can read, write, and run code to finish a task for you
+- 🎬 **Media agent** — generate images & video, or a multi-scene storyboard
+- 🧠 **Chat with your files** — index a folder and ask questions (local RAG)
+- 🪄 **`ai do`** — turn plain English into a shell command, then run it
+- 🎭 **Personas** — swap the assistant's style with named presets
+- 🔌 **Provider-agnostic** — OpenAI, Anthropic, Groq, Gemini, or local Ollama
+- 🔒 **Private by default** — runs fully offline with Ollama, nothing leaves your machine
+- 🎨 **Beautiful** — live streaming + rich Markdown in the terminal
+- 🪄 **Pipe-friendly** — `cat error.log | ai "what broke?"`
+- 💾 **Remembers** — every chat is saved as a session you can revisit
+- 🪶 **Tiny** — pure Python, four small dependencies, no Node, no Docker
+
+## 📦 Install
+
+```bash
+pip install oshell
+```
+
+That's it. You get two commands: `oshell` and the shortcut `ai`.
+
+## ⚡ Quickstart
+
+### Option A — fully local & free (Ollama)
+
+```bash
+# 1. Install Ollama: https://ollama.com
+ollama pull llama3.2
+
+# 2. Chat!
+ai "write a haiku about garbage collection"
+```
+
+### Option B — OpenAI
+
+```bash
+export OPENAI_API_KEY="sk-..."
+ai --provider openai --model gpt-4o-mini "refactor this regex: ^\d{4}-\d{2}$"
+```
+
+## 🧑‍💻 Usage
+
+```bash
+# Interactive chat (type /help inside for commands)
+ai
+
+# One-shot question
+ai "what's the time complexity of quicksort?"
+
+# Pipe context in from anything
+cat main.py | ai "find the bug"
+git diff | ai "write a commit message"
+
+# Pick a provider / model on the fly
+ai -p openai -m gpt-4o "summarize the news"
+ai -p anthropic -m claude-3-5-sonnet-latest "explain this"
+ai -p groq -m llama-3.3-70b-versatile "fast answer please"
+ai -p ollama -m qwen2.5-coder "optimize this loop"
+
+# List available models
+ai models
+```
+
+### Inside an interactive session
+
+| Command         | What it does                       |
+| --------------- | ---------------------------------- |
+| `/help`         | Show available commands            |
+| `/clear`        | Forget the conversation so far     |
+| `/system <txt>` | Change the system prompt on the go |
+| `/exit`         | Quit                               |
+
+## 🤖 Coding agent
+
+oshell ships with an autonomous **coding agent** that can read your files,write new ones, and run commands to complete a task — all sandboxed to the
+current directory, and asking before each write or command.
+
+```bash
+# Let the agent build something for you
+ai agent "create a FastAPI hello-world app with a /health endpoint"
+
+# Point it at a specific folder
+ai agent -d ./my-project "add unit tests for utils.py and run them"
+
+# Skip confirmations (use with care!)
+ai agent --yolo "fix the failing tests"
+
+# Interactive mode — keep giving follow-up tasks, agent remembers context
+ai agent -i
+```
+
+How it works: the agent thinks step-by-step and uses a small set of tools —
+`read_file`, `write_file`, `list_dir`, and `run_command`. Every file write and
+shell command shows you a preview and waits for your **yes** (unless `--yolo`).
+It's confined to the workspace root, so it can't touch files elsewhere.
+
+> 🔒 **Safety first.** The agent cannot escape the workspace directory, and
+> mutating actions require your approval by default.
+
+## 🎬 Media agent
+
+Turn a one-line brief into polished media. The agent first uses the chat LLM
+to **enhance** your brief into a detailed, model-ready prompt (composition,
+lighting, camera, mood…), then generates the image or video.
+
+```bash
+# Images (OpenAI gpt-image-1 / DALL·E 3)
+ai image "a fox in a misty forest at dawn"
+ai image -n 3 -s 1024x1536 "retro sci-fi book cover"
+ai image --raw "exact prompt, no LLM rewrite"
+
+# Video (Replicate text-to-video models)
+ai video "a drone shot flying over a neon cyberpunk city at night"
+ai video -m minimax/video-01 "timelapse of a blooming flower"
+```
+
+Generated files are saved to your Pictures folder under `oshell/` (configurable
+via `media_output_dir`).
+
+**Setup**
+
+```bash
+# Images reuse your OpenAI key:
+export OPENAI_API_KEY="sk-..."
+
+# Video uses Replicate:
+export REPLICATE_API_TOKEN="r8_..."
+# or: ai config set replicate_api_token r8_...
+```
+
+> 💡 Any text-to-video model on [Replicate](https://replicate.com/explore) works —
+> just set `video_model` (e.g. `minimax/video-01`, `luma/ray`, etc.).
+
+### 🎥 Storyboard mode
+
+Turn a one-line story into a multi-scene video. The LLM acts as a **director**,
+breaking your brief into scenes, generating an image for each, then stitching
+them into an MP4 (requires `ffmpeg` for the final stitch).
+
+```bash
+ai storyboard "a seed growing into a giant tree across the seasons"
+ai storyboard -n 6 --seconds 3 "the history of computing in 6 frames"
+```
+
+Each scene image is saved too, so you get usable output even without ffmpeg.
+
+## 🧠 Chat with your files (RAG)
+
+Index a folder once, then ask questions answered from *your* content. Embeddings
+run locally through Ollama (or OpenAI), and the vector store is plain JSON — no
+heavy dependencies.
+
+```bash
+# With Ollama, grab an embedding model first (one time):
+ollama pull nomic-embed-text
+
+ai index ./docs                 # build the index
+ai ask "how do I configure logging?"
+ai ask -k 8 "summarize the auth flow"
+```
+
+## 🪄 Natural-language shell (`ai do`)
+
+Describe what you want; oshell suggests the exact command and runs it after you
+confirm.
+
+```bash
+ai do "compress all PNGs in this folder"
+ai do "find the 5 largest files under /var/log"
+```
+
+> The command is always shown and requires your **yes** before running.
+
+## 🎭 Personas
+
+Swap the assistant's behaviour with named presets (built-ins: `reviewer`,
+`teacher`, `shell`, `rubber-duck`, `concise`, `pirate`).
+
+```bash
+ai --persona reviewer "look at this function"   # one-off
+ai persona list                                  # see them all
+ai persona use teacher                           # set a default
+ai persona add legal "You are a contracts expert. Be precise."
+```
+
+## ⚙️ Configuration
+
+Set defaults once and forget them:
+
+```bash
+ai config set provider openai
+ai config set model gpt-4o-mini
+ai config set openai_api_key sk-...
+ai config show
+```
+
+Or use environment variables: `OPENAI_API_KEY`, `OPENAI_BASE_URL`,
+`ANTHROPIC_API_KEY`, `GROQ_API_KEY`, `GEMINI_API_KEY`, `REPLICATE_API_TOKEN`,
+`OLLAMA_HOST`, `OSHELL_PROVIDER`, `OSHELL_MODEL`.
+
+> 💡 Because oshell speaks the OpenAI API, you can point `OPENAI_BASE_URL`
+> at **any** compatible endpoint (Groq, Together, LM Studio, vLLM…).
+
+## 🛠️ Development
+
+```bash
+git clone https://github.com/djaferiurim/oshell
+cd oshell
+pip install -e ".[dev]"
+ai --version
+
+# Run the test suite
+pytest
+
+# Regenerate the demo GIF (pure Python, no extra tools)
+python tools/make_demo.py demo.gif
+```
+
+## 🤝 Contributing
+
+PRs and ideas welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, project
+layout, and good first issues. Release notes live in [CHANGELOG.md](CHANGELOG.md).
+
+## 📄 License
+
+MIT © djaferiurim

oshell-0.1.1.dist-info/RECORD

@@ -0,0 +1,17 @@
+oshell/__init__.py,sha256=L1E9Xb0wedWKgJk7EoFDFoMrKw6pS1lXHsl-gVTcbZM,85
+oshell/agent.py,sha256=tyxV8QzKcxj9NTFR9tvL02l_nJTSgxzhYOK25UD_Yu4,5346
+oshell/cli.py,sha256=ZmIeLTDwNjY_Y7XLX5siyZCrekkmN6rDiO1Cjjxw1j0,28278
+oshell/config.py,sha256=JRX5z9AG0UjB5iakz2bMVmotb6O_LQPLjcMXFn4LSVM,3086
+oshell/history.py,sha256=Sf_bOhFSTBYdHAuMNVGQHO3oBqkAR4MiWFMbCSPzLYc,1450
+oshell/media.py,sha256=6ejs_cRitK2xnHHMM6SVXF-ckdzFZrP0u_CavPFJ_-Q,6213
+oshell/media_agent.py,sha256=Ur06QMHyK48ZaU2KZfOIGpkDiEYdi_LBkdSJ1Nf5kkY,2335
+oshell/personas.py,sha256=_sDozvDG6dh-yu5LmtDJRmK0PtmuZiuN_9t-jp3LYNc,2860
+oshell/providers.py,sha256=vWHm4B9jmMCnQE8kfTlai59K_WPv6rfO-uH8L6F5Kzc,8809
+oshell/retrieval.py,sha256=Cb8_KQMEIZvgpJLKA8zcy4klm_3w8tycwhXfGqhjzTE,5687
+oshell/storyboard.py,sha256=zIJFBtpTQ9t8EjHmP-nz5leUxYwt5Cq4FTlwPgMiyOI,5451
+oshell/tools.py,sha256=QRKYsLbGBnBnUyZTMVnIR81lELm_4aY8SGhRP2LCS2I,5873
+oshell-0.1.1.dist-info/METADATA,sha256=aIV3A6GaNk-V38WB6VpoVi46-ilwQw2UOFl7-i6U_uU,9138
+oshell-0.1.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+oshell-0.1.1.dist-info/entry_points.txt,sha256=YURcQB5kCTLoT2RgF2pSrbVCJZP6BEuQ8JhPkQQCaXU,76
+oshell-0.1.1.dist-info/licenses/LICENSE,sha256=Ki_ISRgwF3HS1i3jLR5SQSt6PYaJ-7R5EIb0xdK3fXU,1068
+oshell-0.1.1.dist-info/RECORD,,

oshell-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

oshell-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+ai = oshell.cli:main_entry
+oshell = oshell.cli:main_entry

oshell-0.1.1.dist-info/licenses/LICENSE

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