aios-runtime 0.1.0__tar.gz

aios_runtime-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["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 }}
+          cache: pip
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v --tb=short
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install ruff
+        run: pip install ruff
+
+      - name: Ruff check
+        run: ruff check aios/
+
+      - name: Ruff format check
+        run: ruff format --check aios/
+
+  typecheck:
+    name: Type check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]" mypy
+
+      - name: mypy
+        run: mypy aios/ --ignore-missing-imports

aios_runtime-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,85 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build twine
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Check dist
+        run: twine check dist/*
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/aios-runtime/
+    permissions:
+      id-token: write  # OIDC trusted publishing — no API token needed
+
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-github:
+    name: Create GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Extract changelog entry
+        id: changelog
+        run: |
+          VERSION=${GITHUB_REF_NAME#v}
+          NOTES=$(awk "/## \[$VERSION\]/,/## \[/" CHANGELOG.md | head -n -1 | tail -n +2)
+          echo "notes<<EOF" >> $GITHUB_OUTPUT
+          echo "$NOTES" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Create release
+        uses: softprops/action-gh-release@v2
+        with:
+          body: ${{ steps.changelog.outputs.notes }}
+          files: dist/*
+          draft: false
+          prerelease: ${{ contains(github.ref_name, 'alpha') || contains(github.ref_name, 'beta') || contains(github.ref_name, 'rc') }}

aios_runtime-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.env
+.env.example
+*.db
+*.sqlite
+.aios/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/

aios_runtime-0.1.0/.vscode/settings.json

@@ -0,0 +1 @@
+{}

aios_runtime-0.1.0/CHANGELOG.md

@@ -0,0 +1,101 @@
+# Changelog
+
+All notable changes to Ai.os are documented here.
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+Versioning: [Semantic Versioning](https://semver.org/).
+
+---
+
+## [Unreleased]
+
+### Planned
+- Built-in GitHub tool mixin (repos, issues, PRs, search)
+- Built-in Postgres tool mixin (query, insert, schema inspection)
+- Built-in Slack tool mixin (send message, read channel)
+- TypeScript SDK
+- `aios deploy` — self-hosted cloud deployment
+- Visual workflow builder
+
+---
+
+## [0.1.0] — 2026-06-28
+
+First public release.
+
+### Added
+
+**Core runtime**
+- `Agent` base class — persistent identity, memory, tools, crash recovery in one class
+- `@tool` decorator — schema inferred automatically from type hints and docstrings
+- `@schedule("every Xh")` decorator — agent repeats on a cron/interval, survives restarts
+- `Agent.think()` — single-shot LLM call
+- `Agent.think_with_tools()` — agentic loop, LLM selects and calls tools until done
+- `Agent.call_agent()` — blocking call to another agent class, returns text
+- `Agent.spawn_agent()` — fire-and-forget agent in background task
+- `Agent.on_start()` / `Agent.on_stop()` — lifecycle hooks
+- `Agent.launch()` — entry point, auto-loads `.env`, validates API key
+
+**Checkpoint engine** (`aios/runtime/checkpoint.py`)
+- Caches tool call results by `(run_id, tool_name, args_hash)` in SQLite
+- On restart, `run()` re-executes but completed tool calls replay from cache instantly
+- Agent fast-forwards to the first uncompleted call and continues from there
+- No manual checkpoints required
+
+**Memory** (`aios/memory/store.py`)
+- Short-term: in-process key/value, cleared each run
+- Long-term: SQLite-persisted key/value, survives forever
+- Timeline: append-only event log per agent
+
+**Identity** (`aios/identity/core.py`)
+- Persistent UUID per agent name — same agent, same ID across restarts
+- Tracks name, model, version, config
+
+**Model router** (`aios/models/router.py`)
+- Any model in one line: Claude, GPT-4o, Gemini, Mistral, Ollama
+- Powered by [litellm](https://github.com/BerriAI/litellm)
+- Streaming support via `ModelRouter.stream()`
+
+**Built-in tool mixins** (`aios/tools/builtin/`)
+- `WebSearchMixin` — `web_search()` (DuckDuckGo, no key), `fetch_url()` with HTML stripping
+- `FilesystemMixin` — `read_file()`, `write_file()`, `list_directory()`, `delete_file()`, `file_exists()` with cwd sandboxing
+- `ShellMixin` — `run_command()` (allowlist support), `run_python()` with timeout
+- `HttpMixin` — `http_get()`, `http_post()`, `http_put()`, `http_delete()`
+
+**CLI** (`aios` command)
+- `aios init [name]` — scaffold new agent project
+- `aios run <file>` — run agent (foreground, `--detach`, `--watch`)
+- `aios list` — list all agents with status
+- `aios status <name>` — status + run history
+- `aios logs <name>` — show logs (`-f` to follow, cross-platform)
+- `aios stop <name>` — stop agent
+- `aios restart <name>` — stop + restart (resumes from checkpoint)
+- `aios memory <name>` — inspect long-term memory
+- `aios ui` — open web dashboard
+- `aios version` — show version
+
+**Web UI** (`aios/web/`)
+- FastAPI backend with SSE log streaming
+- Live dashboard: running agents, logs, memory inspector, run history
+- Auto-refreshes every 5 seconds
+
+**Config** (`aios/config.py`)
+- Auto-discovers and loads `.env` from cwd upward
+- Validates API key for the configured model on startup
+- Clear error messages with setup instructions when keys are missing
+
+**Testing**
+- 54 tests across 5 test files
+- `pytest-asyncio` for async tests
+- Covers: memory store, checkpoint engine (including crash-resume), tool registry, agent lifecycle, built-in tools, scheduling, config
+
+**Project**
+- `pyproject.toml` with hatchling build, ruff, mypy config
+- GitHub Actions CI: test (3.10/3.11/3.12), lint (ruff), type check (mypy)
+- `CONTRIBUTING.md` with dev setup, commit conventions, testing guide
+- `.env.example` with all supported variables
+- MIT license
+
+---
+
+[Unreleased]: https://github.com/aios-runtime/aios/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/aios-runtime/aios/releases/tag/v0.1.0

aios_runtime-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,112 @@
+# Contributing to Ai.os
+
+Thank you for contributing. This document covers everything you need to go from zero to a merged pull request.
+
+## Setup
+
+```bash
+git clone https://github.com/aios-runtime/aios
+cd aios
+python -m venv .venv
+source .venv/bin/activate      # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+cp .env.example .env           # add your API key
+```
+
+Verify everything works:
+
+```bash
+pytest tests/        # 37 tests, all green
+ruff check aios/     # no lint errors
+```
+
+## Project structure
+
+```
+aios/
+  agent.py          Base Agent class — the core API
+  config.py         .env loading, API key validation
+  scheduling.py     @schedule decorator
+  identity/         Persistent agent UUID and config
+  memory/           Short-term + long-term SQLite memory
+  models/           litellm model router
+  runtime/          Checkpoint engine + process manager
+  tools/            @tool decorator and registry
+  web/              FastAPI dashboard
+  cli/              Typer CLI (aios run/list/logs/…)
+tests/
+examples/
+```
+
+## Making changes
+
+1. Fork the repo and create a branch: `git checkout -b feat/your-feature`
+2. Write your code. Write tests for it.
+3. Run `pytest tests/` — all tests must pass.
+4. Run `ruff check aios/ && ruff format aios/` — no lint errors.
+5. Open a pull request against `main`.
+
+## Commit conventions
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat: add @schedule decorator
+fix: agent crash on empty tool response
+docs: add multi-agent example
+test: cover checkpoint resume semantics
+refactor: simplify tool schema inference
+```
+
+Keep subject lines under 72 characters. No period at the end.
+
+## Writing tests
+
+Tests live in `tests/`. All tests are async-friendly via `pytest-asyncio`.
+
+```python
+async def test_my_feature(tmp_path: Path) -> None:
+    store = MemoryStore(agent_id="test-001", db_path=tmp_path / "test.db")
+    await store.setup()
+    await store.save("key", "value")
+    assert await store.load("key") == "value"
+```
+
+Rules:
+- Every new feature needs at least one test.
+- Every bug fix needs a regression test.
+- Use `tmp_path` for all file I/O — never write to real `~/.aios` in tests.
+- Mock LLM calls — never make real API calls in tests.
+
+## What we accept
+
+**Yes:**
+- Bug fixes with regression tests
+- Performance improvements with benchmarks
+- New built-in tools (GitHub, Slack, Postgres, S3…)
+- Documentation improvements
+- New example agents
+
+**Discuss first (open an issue):**
+- New runtime targets (TypeScript SDK, edge runtime)
+- Breaking changes to the Agent API
+- New CLI commands
+- Web UI changes
+
+**Not now:**
+- Visual workflow builder
+- Marketplace
+- Blockchain
+- Mobile runtime
+
+## Code style
+
+- Python 3.10+, `from __future__ import annotations` in every file
+- Type hints on all public functions
+- No comments that describe *what* the code does — only *why*
+- `ruff` for formatting and linting — run `ruff format aios/` before committing
+- Function names are verbs, class names are nouns
+
+## Questions
+
+Open an issue or join the Discord. We respond within 24 hours.

aios_runtime-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ai.os contributors
+
+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.