Metadata-Version: 2.4
Name: ageos
Version: 0.1.0
Summary: AgeOS MVP CLI, sandbox, local model scheduler, and Python integrations.
Author: AgeOS
License: Proprietary
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: huggingface-hub>=0.23
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.31
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Provides-Extra: vllm
Requires-Dist: vllm>=0.5; extra == "vllm"
Provides-Extra: langchain
Requires-Dist: langchain-core<0.4,>=0.2; extra == "langchain"

# AgeOS MVP

AgeOS is a Linux-first local agent runtime for sandboxed agents, local LLM routing, GPU/RAM-aware scheduling, and Python integration shims.

## Install From Source

```bash
./scripts/install-deps.sh
./scripts/build.sh
ageos --help
```

`./scripts/build.sh` performs a system-wide source install: native binaries go under `/usr/local`, the managed Python runtime goes under `/opt/ageos`, and global launchers are linked into `/usr/local/bin`. This avoids Ubuntu's system Python `pip` restrictions while still making `ageos` available on PATH for every shell. The MVP expects `llama-server` on `PATH` for the default local backend. vLLM is optional and installed with:

```bash
sudo /opt/ageos/bin/python -m pip install ".[vllm]"
```

## Commands

```bash
ageos poc --speciality default-instruct
ageos prompt --speciality code-review --structure example.json --text "Review this diff"
ageos run --binary ./agent.py --niceness 10
ageos ps
ageos queue --watch
ageos dashboard
```

`--niceness` is an AgeOS resource priority only. It controls GPU admission, RAM/VRAM budgets, model eviction, and memory-pressure behavior. It does not call Linux `nice`, `setpriority`, or `ionice`.

## Examples

Run the basic Python shim agent through the AgeOS sandbox:

```bash
ageos run --binary ./examples/basic_agent.py --speciality default-instruct --memory 16G
```

The agent prints its AgeOS environment, calls the OpenAI-style Python shim, and prints the local model response.

## RAM States

AgeOS tracks three memory pressure states:

- `available`: jobs admit normally; niceness controls tie-breaks and preload order.
- `low`: lower niceness agents receive RAM/VRAM first; background jobs wait.
- `no_ram`: low-priority work is queued or rejected; only highest-priority jobs can run after idle models are freed.

## Sandbox

`ageos run` is Linux-only. The native sandbox uses namespaces, read-only mounts, dropped capabilities, no-new-privs, seccomp when available, Landlock hook points, and cgroups v2. Agents do not receive direct GPU device access and must request inference through AgeOS.

For local development on non-Linux platforms only:

```bash
ageos run --binary ./agent.py --unsafe-no-sandbox
```

## Python Shims

```python
from ageos.integrations.openai_shim import AgeosOpenAI

client = AgeosOpenAI(speciality="code-review", niceness=5)
response = client.chat.completions.create(
    model="ignored",
    messages=[{"role": "user", "content": "hello"}],
)
print(response.choices[0].message.content)
```

## Packaging Targets

- Snap Store: `ageos` and optional `ageos-vllm`
- APT/PPA: `ageos`, `ageos-vllm`
- PyPI: `ageos`

Release automation lives in `.github/workflows/release.yml`. Push a `v*` tag to build Python, Debian, and Snap artifacts, attach them to a GitHub Release, and publish to configured stores. TestPyPI publishing requires the `TEST_PYPI_API_TOKEN` repository secret. PyPI publishing requires the `PYPI_API_TOKEN` repository secret. Snap Store publishing requires the `SNAPCRAFT_STORE_CREDENTIALS` repository secret and currently releases the `devel` snap to the `edge` channel.
