oshell 0.1.1__tar.gz

oshell-0.1.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,64 @@
+name: Bug report
+description: Report something that isn't working
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: Thanks for taking the time to file a bug report!
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear description of the bug.
+      placeholder: When I run `ai ...`, I get ...
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Run `ai ...`
+        2. ...
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: dropdown
+    id: provider
+    attributes:
+      label: Provider
+      options:
+        - Ollama
+        - OpenAI
+        - Groq
+        - Gemini
+        - Anthropic
+        - Other / not sure
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: oshell version
+      description: Output of `ai --version` (or the version in pyproject.toml).
+      placeholder: "0.1.0"
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: OS and Python version
+      placeholder: "Windows 11, Python 3.12"
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / traceback
+      render: shell

oshell-0.1.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Questions & discussions
+    url: https://github.com/djaferiurim/oshell/discussions
+    about: Ask questions and share ideas here.

oshell-0.1.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,27 @@
+name: Feature request
+description: Suggest an idea for oshell
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: Describe the use case or pain point.
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: What would you like oshell to do?
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context

oshell-0.1.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,21 @@
+## Summary
+
+<!-- What does this PR change and why? -->
+
+## Related issue
+
+<!-- e.g. Closes #123 -->
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Documentation
+- [ ] Refactor / chore
+
+## Checklist
+
+- [ ] Tests pass (`pytest`)
+- [ ] Added/updated tests where relevant
+- [ ] Updated `CHANGELOG.md`
+- [ ] Updated docs/README if behavior changed

oshell-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }} / ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package + dev deps
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest -q
+
+      - name: Smoke-test the CLI
+        run: |
+          oshell --version
+          oshell persona list

oshell-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/oshell
+    permissions:
+      id-token: write  # for trusted publishing (no API token needed)
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

oshell-0.1.1/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+env/
+
+# Packaging
+*.whl
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE / OS
+.vscode/
+.idea/
+.DS_Store
+
+# oshell local data (in case run from repo)
+sessions/
+config.json

oshell-0.1.1/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.1] - 2026-06-12
+
+### Changed
+- Renamed the project to **oshell**; install with `pip install oshell`.
+- CLI commands are now `oshell` and the shortcut `ai`.
+- Environment variables renamed to `OSHELL_PROVIDER` / `OSHELL_MODEL`.
+- Repository moved to https://github.com/djaferiurim/oshell.
+
+## [0.1.0] - 2026-06-11
+
+### Added
+- **Chat** — streaming terminal chat with live Markdown rendering, history, slash
+  commands, and stdin pipe support.
+- **Coding agent** — sandboxed ReAct agent (`ai agent`) with read/write/list/run
+  tools, approval prompts, and `--yolo` auto-approve.
+- **Interactive agent mode** (`ai agent -i`) — keeps conversation state across
+  tasks so follow-ups remember earlier work.
+- **Media generation** — `ai image` and `ai video` with an LLM prompt-enhancing
+  media agent.
+- **Storyboard mode** (`ai storyboard`) — plans scenes, renders an image per
+  scene, and stitches them into an MP4 via ffmpeg.
+- **Providers** — Ollama, OpenAI, Groq, Gemini, and Anthropic.
+- **Personas** — built-in presets plus custom user personas.
+- **Natural-language shell** (`ai do`) — turns plain English into shell commands
+  with confirmation.
+- **Local RAG** — `ai index` / `ai ask` over your files with pure-Python cosine
+  search.
+- Test suite (pytest), GitHub Actions CI matrix, PyPI publish workflow, demo
+  tape, and contributing guide.
+
+[Unreleased]: https://github.com/djaferiurim/oshell/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/djaferiurim/oshell/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/djaferiurim/oshell/releases/tag/v0.1.0

oshell-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing to oshell
+
+Thanks for your interest in making oshell better! 🐚
+
+## Getting started
+
+```bash
+git clone https://github.com/djaferiurim/oshell
+cd oshell
+pip install -e ".[dev]"
+pytest          # make sure the suite is green
+```
+
+## Project layout
+
+```
+src/oshell/
+  cli.py          # Typer commands & entry point
+  config.py       # config loading / persistence
+  providers.py    # LLM backends (OpenAI, Ollama, Anthropic, Groq, Gemini)
+  agent.py        # autonomous coding agent (ReAct loop)
+  tools.py        # sandboxed file/command tools for the agent
+  media.py        # image (OpenAI) + video (Replicate) generation
+  media_agent.py  # LLM prompt-enhancement for media
+  storyboard.py   # multi-scene story → images → stitched video
+  retrieval.py    # local RAG (index + search)
+  personas.py     # system-prompt presets
+tests/            # pytest suite
+```
+
+## How to contribute
+
+1. **Open an issue first** for anything non-trivial so we can align on the approach.
+2. Create a branch: `git checkout -b feature/my-thing`.
+3. Make your change with a focused commit history.
+4. Add or update tests in `tests/`.
+5. Run `pytest` and make sure everything passes.
+6. Open a pull request describing the *why*, not just the *what*.
+
+## Guidelines
+
+- Keep dependencies minimal — oshell's appeal is being lightweight.
+- Match the existing style (type hints, short docstrings, `rich` for output).
+- New network calls should fail gracefully with a clear, actionable message.
+- Anything that writes files or runs commands must respect the approval flow.
+
+## Good first issues
+
+- 🎨 Add a new built-in **persona** preset.
+- 🔌 Add another **provider adapter** (e.g. Mistral, Cohere, OpenRouter).
+- 🧰 Add a new **agent tool** (e.g. `apply_patch`, `search_files`).
+- 💬 Add a new **slash command** to the interactive chat.
+- 🧪 Increase **test coverage** for `cli.py` helpers.
+- 📝 Improve docs, examples, or the demo tape.
+
+## Code of conduct
+
+Be kind and constructive. We're all here to build something fun and useful.

oshell-0.1.1/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.

oshell-0.1.1/PKG-INFO

@@ -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