Metadata-Version: 2.5
Name: alinux
Version: 0.1.4
Summary: Alinux AI orchestration shell for minimal Linux desktops
Author: Alinux contributors
License: MIT
Keywords: ai,automation,desktop,fluxbox,linux
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Desktop Environment
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == 'dev'
Requires-Dist: openai<2,>=1.40.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Provides-Extra: openai
Requires-Dist: openai<2,>=1.40.0; extra == 'openai'
Description-Content-Type: text/markdown

# Alinux

Alinux is an AI orchestration shell for a minimal Debian 12 desktop running
Fluxbox. It converts natural-language requests into a small, validated set of
desktop actions.

## Install

```bash
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade --no-cache-dir --index-url https://pypi.org/simple 'alinux[openai]'
python -c "import alinux; print(alinux.__version__)"
```

The base package has no compiled model dependency. Use `python -m pip install
alinux` when running without an LLM, or install the `openai` extra for OpenAI,
Groq, and other OpenAI-compatible providers.

When no API key is configured, Alinux uses a local Ollama model instead of
stopping. Install Ollama, start it, and download the lightweight default model:

```bash
curl -fsSL https://ollama.com/install.sh | sh
ollama pull llama3.2:3b
alinux
```

Set `ALINUX_LOCAL_MODEL` to use another model already installed in Ollama.

For model access, export a key and optionally choose a provider/model. Any
OpenAI-compatible API can be configured with a custom endpoint:

```bash
export ALINUX_API_KEY='your-key'
export ALINUX_MODEL='gpt-4o-mini'
export ALINUX_API_BASE_URL='https://your-provider.example/v1'
```

To use the built-in Groq/Llama configuration from the command line, set your
Groq key and pass the flag:

```bash
export GROQ_API_KEY='your-groq-key'
alinux --use-default-groq-api
```

The flag selects `llama-3.3-70b-versatile` and Groq's API endpoint. It does
not embed or fetch a secret key.

Groq is supported directly, including Alinux's built-in open model preset:

```bash
export ALINUX_PROVIDER='groq'
export ALINUX_API_KEY='your-groq-key'
alinux
```

With `ALINUX_PROVIDER=groq` and no model override, Alinux uses
`llama-3.3-70b-versatile` at Groq's OpenAI-compatible endpoint. You can also
select it explicitly with `ALINUX_MODEL=llama-3.3-70b-versatile`.

The desktop hooks expect `xdotool`, `amixer`, `free`, and `uptime`. Missing
tools are reported as readable responses rather than terminating Alinux.

## Run

```bash
alinux
```

Open the graphical Alinux window from a terminal with:

```bash
alinux open
```

To add **Open Alinux** to the Fluxbox desktop context menu, run this once
inside the Fluxbox session:

```bash
alinux install-fluxbox-menu
```

Then restart or reconfigure Fluxbox. The installer uses the active Python
interpreter and writes GUI errors to `~/.cache/alinux/gui.log`, so menu
launches continue to work even when Fluxbox has a minimal `PATH`. It updates
`~/.fluxbox/menu` without replacing your existing entries. The GUI requires
Debian's `python3-tk` package and a valid `DISPLAY`.

Type requests such as `show system status`, `turn the volume down`, or
`open the terminal`. Enter `quit` or press `Ctrl-D` to exit.

Alinux never executes arbitrary shell text from the model. Only the operations
listed in its system prompt and `system_controls.py` are routable.