cliara 0.2.0__tar.gz

cliara-0.2.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: cliara
+Version: 0.2.0
+Summary: An AI-powered shell that understands natural language and macros
+Author: Cliara Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/yourusername/cliara
+Project-URL: Documentation, https://github.com/yourusername/cliara#readme
+Project-URL: Repository, https://github.com/yourusername/cliara
+Project-URL: Issues, https://github.com/yourusername/cliara/issues
+Keywords: cli,shell,ai,natural-language,macros,automation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: System :: Shells
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: prompt-toolkit>=3.0.0
+Requires-Dist: pygments>=2.0.0
+Requires-Dist: thefuzz>=0.20.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Provides-Extra: ai
+Requires-Dist: openai>=1.0.0; extra == "ai"
+Requires-Dist: anthropic>=0.8.0; extra == "ai"
+Provides-Extra: postgres
+Requires-Dist: psycopg2-binary>=2.9.0; extra == "postgres"
+Provides-Extra: all
+Requires-Dist: cliara[ai,postgres]; extra == "all"
+
+# Cliara - AI-Powered Shell
+
+An intelligent shell wrapper that understands natural language and macros.
+
+## Quick Start
+
+```bash
+# Install
+pip install -e .
+
+# Setup environment
+cp .env.example .env
+# Edit .env and add your OPENAI_API_KEY
+
+# Run
+cliara
+```
+
+## Documentation
+
+- **[Complete Guide](docs/README.md)** - Full documentation
+- **[Quick Start](docs/QUICKSTART.md)** - Get started in 5 minutes
+
+## What is Cliara?
+
+Cliara wraps your existing shell and adds:
+- 🗣️ Natural language commands with `?` prefix (Phase 2)
+- 📦 Powerful macro system (create, edit, delete, run)
+- 🔍 Semantic history search: `? find when I fixed the login` or `? what did I run to deploy`
+- 🛡️ Safety checks for dangerous operations
+- 💾 Save last command as macro instantly
+- 🔄 Persistent command history with arrow-key recall across sessions
+- ✏️ Rename macros without recreating them
+- 📂 Proper `cd` handling (changes Cliara's own working directory)
+- 🚀 Normal commands work unchanged
+
+## Installation
+
+```bash
+# 1. Clone the repo
+git clone https://github.com/yourusername/cliara.git
+cd cliara
+
+# 2. Install dependencies
+pip install -e .
+
+# 3. Setup environment
+cp .env.example .env
+# Edit .env and add your OPENAI_API_KEY
+
+# 4. Run
+cliara
+```
+
+## Usage
+
+```bash
+# Start Cliara
+cliara
+
+# Normal commands work
+cliara:proj > ls -la
+cliara:proj > git status
+
+# Natural language (requires OPENAI_API_KEY)
+cliara:proj > ? kill process on port 3000
+
+# Create a macro
+cliara:proj > macro add test
+  > echo Step 1
+  > echo Step 2
+  > 
+
+# Edit an existing macro
+cliara:proj > macro edit test
+  > echo Updated Step 1
+  > echo Updated Step 2
+  > 
+
+# Run it
+cliara:proj > test
+
+# Rename a macro
+cliara:proj > macro rename old-name new-name
+
+# Save last command
+cliara:proj > echo "hello"
+cliara:proj > macro save last as hello
+
+# cd works correctly (changes Cliara's own directory)
+cliara:proj > cd src
+cliara:src >
+```
+
+## Features
+
+### Phase 1 ✅ (Complete)
+- Shell wrapper with pass-through
+- Interactive macro system (add, edit, delete, rename, show, run, search)
+- Save last command as macro
+- Persistent command history (`~/.cliara/history.txt`) with arrow-key recall
+- Multi-tier safety checks
+- Auto-configuration
+
+### Phase 2 ✅ (Complete)
+- LLM integration (OpenAI)
+- Natural language → commands
+- Context-aware suggestions
+- **Semantic history search**: `? find ...` / `? when did I ...` / `? what did I run ...` — search past commands by intent (stored in `~/.cliara/semantic_history.json`)
+
+### Storage Backends
+- **JSON** (default) - Simple file-based storage
+- **PostgreSQL** - Scalable database backend for millions of macros
+  - See [PostgreSQL Setup Guide](docs/POSTGRES_SETUP.md)
+
+## Requirements
+
+- Python 3.8+
+- Windows, macOS, or Linux
+
+### Windows Users
+After installation, you may need to add Python Scripts to your PATH:
+```
+C:\Users\<YourName>\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.12_qbz5n2kfra8p0\LocalCache\local-packages\Python312\Scripts
+```
+Or restart your computer for PATH changes to take effect.
+
+## Version
+
+**v0.2.0** - Phase 2 Complete
+- ✅ Natural language support
+- ✅ Windows compatibility fixes
+- ✅ PostgreSQL backend support
+
+## License
+
+MIT
+
+---
+
+**See [docs/README.md](docs/README.md) for complete documentation.**

cliara-0.2.0/README.md

@@ -0,0 +1,141 @@
+# Cliara - AI-Powered Shell
+
+An intelligent shell wrapper that understands natural language and macros.
+
+## Quick Start
+
+```bash
+# Install
+pip install -e .
+
+# Setup environment
+cp .env.example .env
+# Edit .env and add your OPENAI_API_KEY
+
+# Run
+cliara
+```
+
+## Documentation
+
+- **[Complete Guide](docs/README.md)** - Full documentation
+- **[Quick Start](docs/QUICKSTART.md)** - Get started in 5 minutes
+
+## What is Cliara?
+
+Cliara wraps your existing shell and adds:
+- 🗣️ Natural language commands with `?` prefix (Phase 2)
+- 📦 Powerful macro system (create, edit, delete, run)
+- 🔍 Semantic history search: `? find when I fixed the login` or `? what did I run to deploy`
+- 🛡️ Safety checks for dangerous operations
+- 💾 Save last command as macro instantly
+- 🔄 Persistent command history with arrow-key recall across sessions
+- ✏️ Rename macros without recreating them
+- 📂 Proper `cd` handling (changes Cliara's own working directory)
+- 🚀 Normal commands work unchanged
+
+## Installation
+
+```bash
+# 1. Clone the repo
+git clone https://github.com/yourusername/cliara.git
+cd cliara
+
+# 2. Install dependencies
+pip install -e .
+
+# 3. Setup environment
+cp .env.example .env
+# Edit .env and add your OPENAI_API_KEY
+
+# 4. Run
+cliara
+```
+
+## Usage
+
+```bash
+# Start Cliara
+cliara
+
+# Normal commands work
+cliara:proj > ls -la
+cliara:proj > git status
+
+# Natural language (requires OPENAI_API_KEY)
+cliara:proj > ? kill process on port 3000
+
+# Create a macro
+cliara:proj > macro add test
+  > echo Step 1
+  > echo Step 2
+  > 
+
+# Edit an existing macro
+cliara:proj > macro edit test
+  > echo Updated Step 1
+  > echo Updated Step 2
+  > 
+
+# Run it
+cliara:proj > test
+
+# Rename a macro
+cliara:proj > macro rename old-name new-name
+
+# Save last command
+cliara:proj > echo "hello"
+cliara:proj > macro save last as hello
+
+# cd works correctly (changes Cliara's own directory)
+cliara:proj > cd src
+cliara:src >
+```
+
+## Features
+
+### Phase 1 ✅ (Complete)
+- Shell wrapper with pass-through
+- Interactive macro system (add, edit, delete, rename, show, run, search)
+- Save last command as macro
+- Persistent command history (`~/.cliara/history.txt`) with arrow-key recall
+- Multi-tier safety checks
+- Auto-configuration
+
+### Phase 2 ✅ (Complete)
+- LLM integration (OpenAI)
+- Natural language → commands
+- Context-aware suggestions
+- **Semantic history search**: `? find ...` / `? when did I ...` / `? what did I run ...` — search past commands by intent (stored in `~/.cliara/semantic_history.json`)
+
+### Storage Backends
+- **JSON** (default) - Simple file-based storage
+- **PostgreSQL** - Scalable database backend for millions of macros
+  - See [PostgreSQL Setup Guide](docs/POSTGRES_SETUP.md)
+
+## Requirements
+
+- Python 3.8+
+- Windows, macOS, or Linux
+
+### Windows Users
+After installation, you may need to add Python Scripts to your PATH:
+```
+C:\Users\<YourName>\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.12_qbz5n2kfra8p0\LocalCache\local-packages\Python312\Scripts
+```
+Or restart your computer for PATH changes to take effect.
+
+## Version
+
+**v0.2.0** - Phase 2 Complete
+- ✅ Natural language support
+- ✅ Windows compatibility fixes
+- ✅ PostgreSQL backend support
+
+## License
+
+MIT
+
+---
+
+**See [docs/README.md](docs/README.md) for complete documentation.**

cliara-0.2.0/cliara/__init__.py

@@ -0,0 +1,18 @@
+"""
+Cliara - An AI-powered shell that understands natural language and macros.
+
+A shell wrapper that lets you:
+- Run normal terminal commands (pass-through)
+- Use natural language with ? prefix
+- Create and run macros
+- Save command history as macros
+"""
+
+__version__ = "0.2.0"
+__author__ = "Cliara Contributors"
+
+from cliara.shell import CliaraShell
+from cliara.macros import MacroManager
+from cliara.safety import SafetyChecker
+
+__all__ = ["CliaraShell", "MacroManager", "SafetyChecker"]

cliara-0.2.0/cliara/agents/__init__.py

@@ -0,0 +1,46 @@
+"""
+Agent registry: builds AGENT_REGISTRY from agent modules and prompts.
+"""
+
+from pathlib import Path
+from typing import Any, Dict
+
+from cliara.agents import nl_to_commands as _nl
+from cliara.agents import fix as _fix
+from cliara.agents import explain as _explain
+from cliara.agents import history_summary as _history_summary
+from cliara.agents import history_search as _history_search
+from cliara.agents import commit_and_deploy as _commit_deploy
+from cliara.agents import copilot_explain as _copilot_explain
+
+_PROMPTS_DIR = Path(__file__).resolve().parent / "prompts"
+
+
+def _load_prompt(name: str) -> str:
+    path = _PROMPTS_DIR / f"{name}.txt"
+    return path.read_text(encoding="utf-8").strip()
+
+
+def _build_registry() -> Dict[str, Dict[str, Any]]:
+    registry: Dict[str, Dict[str, Any]] = {}
+    all_agents = (
+        _nl.AGENTS
+        | _fix.AGENTS
+        | _explain.AGENTS
+        | _history_summary.AGENTS
+        | _history_search.AGENTS
+        | _commit_deploy.AGENTS
+        | _copilot_explain.AGENTS
+    )
+    for name, cfg in all_agents.items():
+        registry[name] = {
+            "system": _load_prompt(name),
+            "temperature": cfg["temperature"],
+            "max_tokens": cfg["max_tokens"],
+        }
+    return registry
+
+
+AGENT_REGISTRY: Dict[str, Dict[str, Any]] = _build_registry()
+
+__all__ = ["AGENT_REGISTRY"]

cliara-0.2.0/cliara/agents/commit_and_deploy.py

@@ -0,0 +1,12 @@
+"""Commit message and deploy agents."""
+
+AGENTS = {
+    "commit_message": {
+        "temperature": 0.2,
+        "max_tokens": 100,
+    },
+    "deploy": {
+        "temperature": 0.2,
+        "max_tokens": 500,
+    },
+}

cliara-0.2.0/cliara/agents/copilot_explain.py

@@ -0,0 +1,8 @@
+"""Copilot Gate explain agent: single-sentence command explanation + risk factors."""
+
+AGENTS = {
+    "copilot_explain": {
+        "temperature": 0.1,
+        "max_tokens": 120,
+    },
+}

cliara-0.2.0/cliara/agents/explain.py

@@ -0,0 +1,8 @@
+"""Explain agent: explains shell commands in plain English."""
+
+AGENTS = {
+    "explain": {
+        "temperature": 0.3,
+        "max_tokens": 200,
+    },
+}

cliara-0.2.0/cliara/agents/fix.py

@@ -0,0 +1,8 @@
+"""Fix agent: explains command errors and suggests fixes."""
+
+AGENTS = {
+    "fix": {
+        "temperature": 0.2,
+        "max_tokens": 600,  # local models need extra room for JSON explanation fields
+    },
+}

cliara-0.2.0/cliara/agents/history_search.py

@@ -0,0 +1,8 @@
+"""History search agent: match user intent to numbered history entries."""
+
+AGENTS = {
+    "history_search": {
+        "temperature": 0.2,
+        "max_tokens": 100,
+    },
+}

cliara-0.2.0/cliara/agents/history_summary.py

@@ -0,0 +1,8 @@
+"""History summary agent: one-sentence summary of a command for semantic history."""
+
+AGENTS = {
+    "history_summary": {
+        "temperature": 0.2,
+        "max_tokens": 120,
+    },
+}

cliara-0.2.0/cliara/agents/nl_to_commands.py

@@ -0,0 +1,8 @@
+"""NL-to-commands agent: converts natural language to shell commands."""
+
+AGENTS = {
+    "nl_to_commands": {
+        "temperature": 0.3,
+        "max_tokens": 800,  # local models are more verbose; need room for JSON + preamble
+    },
+}