Metadata-Version: 2.4
Name: jugaad-agent
Version: 0.1.4
Summary: Local-first self-healing Ubuntu terminal agent. Type in English, get shell commands with risk checks and smart retries.
Author: Dhruva
License-Expression: MIT
Project-URL: Homepage, https://github.com/dhruva3223/jugaad-agent
Project-URL: Repository, https://github.com/dhruva3223/jugaad-agent
Project-URL: Issues, https://github.com/dhruva3223/jugaad-agent/issues
Keywords: cli,agent,terminal,ubuntu,linux,ollama,langgraph,llm,bash,shell,automation,ai,self-healing
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Terminals
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: langgraph>=0.2.0
Requires-Dist: langchain-ollama>=0.1.0
Requires-Dist: langchain-core>=0.3.0
Requires-Dist: rich>=13.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Dynamic: license-file

# JugaadAgent 🔧

> **जुगाड़** *(joo-gaad)* - the Indian art of resourceful problem-solving.

Type what you want in plain English. JugaadAgent generates the shell command, checks the risk, and retries with real diagnostics when it fails. Runs entirely on your machine via Ollama - no cloud, no API costs.

---

## Install

```bash
pip install jugaad-agent
ollama pull qwen2.5-coder:latest
```

Or use `pipx install jugaad-agent` if you prefer isolated CLI tools.

**Requirements:** Linux (Ubuntu recommended), Python 3.10+, [Ollama](https://ollama.com/)

---

## Usage

```bash
jugaad "free port 8080"
jugaad "find files larger than 100MB in /var/log"
jugaad "install and start nginx" --dry-run
jugaad "something is eating my disk - figure out what"
```

Short alias: `jaa` works everywhere `jugaad` does.

---

## How it works

```
memory → generator → guardrail → executor
           ↑                         │
           └───── fail + diagnose ───┘
```

When a command fails, JugaadAgent doesn't retry blindly. It runs `lsof`, checks for missing binaries, reads permission errors - then sends that context back to the model before retrying.

| Module | What it does |
|--------|--------------|
| `state.py` | Pydantic state + history accumulator |
| `nodes.py` | LLM generation + shell execution |
| `guardrails.py` | Risk scan + human approval (HITL) |
| `diagnostics.py` | Enriches stderr with Ubuntu telemetry |
| `memory.py` | Loads `.agent_rules.md` from working directory |
| `graph.py` | LangGraph state machine |

---

## Safety

JugaadAgent runs real shell commands on your machine.

| Risk level | Behavior |
|------------|----------|
| **LOW** | Runs automatically |
| **MEDIUM / HIGH** | Stops and asks `[Y]es / [N]o / [E]dit` before executing |

**Flags:**
- `--dry-run` - generate without executing
- `--yes` / `-y` - skip approval prompts (use carefully)
- `--max-retries` - hard cap on self-heal loops (default: 3)

---

## Options

```bash
jugaad "task" -m llama3.2:3b      # set model (saved for future runs)
jugaad "task" --max-retries 5
jugaad "task" --dry-run
jugaad "task" --yes
jugaad --version
```

### Model selection priority
1. `-m` / `--model` flag (persisted to `~/.config/jugaad-agent/`)
2. `JUGAAD_MODEL` env (one-time override, not saved)
3. Saved preference from a previous `-m`
4. Built-in default: `qwen2.5-coder:latest`

### Environment variables

| Variable | Default | Purpose |
|----------|---------|---------|
| `JUGAAD_MODEL` | _(unset)_ | Override model for this run only |
| `JUGAAD_BASE_URL` | `http://127.0.0.1:11434` | Ollama API endpoint |
| `JUGAAD_MAX_RETRIES` | `3` | Self-heal retry ceiling |

---

## Workspace rules

Add `.agent_rules.md` to any project directory - JugaadAgent reads it on every run. Use it for preferred tools, things to avoid, or project-specific context.

Example:

```markdown
- Prefer `rg` over `grep` when searching code
- Use `uv` instead of `pip` for Python installs
- Never delete anything in `/data/production`
```

See [`.agent_rules.md.example`](.agent_rules.md.example) for more ideas.

---

## Development

```bash
git clone https://github.com/dhruva3223/jugaad-agent.git
cd jugaad-agent
pip install -e ".[dev]"
```

**Build for PyPI:**

```bash
rm -rf dist/ build/ src/*.egg-info
python -m build
twine check dist/*
twine upload dist/*
```

---

## License

MIT - see [LICENSE](LICENSE)

---

## Contributing

Issues and PRs welcome at [github.com/dhruva3223/jugaad-agent](https://github.com/dhruva3223/jugaad-agent/issues)
