gh-ai-runner 0.1.3__tar.gz

gh_ai_runner-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tanish Chauhan
+
+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.

gh_ai_runner-0.1.3/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: gh-ai-runner
+Version: 0.1.3
+Summary: Serverless AI inference via GitHub Actions — no server required
+Author: Tanish Chauhan
+License: MIT
+Project-URL: Homepage, https://github.com/TanishC4444/servai
+Project-URL: Repository, https://github.com/TanishC4444/servai
+Keywords: ai,llm,inference,github-actions,llama,serverless
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# Servai
+
+[![PyPI version](https://badge.fury.io/py/servai.svg)](https://badge.fury.io/py/servai)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+
+**Serverless AI inference via GitHub Actions. No server. No GPU. No infrastructure.**
+
+Run open-source LLMs directly through GitHub's free CI/CD runners — just a GitHub token and a prompt. `servai` handles everything else: repo creation, workflow setup, model downloading, caching, and output retrieval.
+
+Built by [Tanish Chauhan](https://github.com/TanishC4444)
+
+---
+
+## How it works
+
+When you call `ai_call()`:
+
+1. Creates a private GitHub repo (once, automatically)
+2. Commits a workflow + inference script into it
+3. Dispatches a `workflow_dispatch` GitHub Actions run
+4. The runner downloads and caches the model (GGUF quantized, ~0.6 GB)
+5. Runs inference via `llama-cpp-python`
+6. Uploads the output as an artifact
+7. Downloads and returns the output to you as a string
+
+No server is ever running between calls. Each call spins up a fresh GitHub Actions runner, runs inference, and shuts down.
+
+---
+
+## Install
+```bash
+pip install servai
+```
+
+**Requirements:**
+- Python 3.9+
+- A GitHub account with a personal access token (PAT)
+- Token scopes needed: `repo`, `workflow`
+
+---
+
+## Getting a GitHub Token
+
+You need a GitHub Personal Access Token (PAT) with `repo` and `workflow` scopes.
+
+**Classic token (recommended):**
+
+1. Go to [github.com/settings/tokens](https://github.com/settings/tokens)
+2. Click **Generate new token > Generate new token (classic)**
+3. Give it a name (e.g. `servai`)
+4. Set an expiration
+5. Check these scopes:
+   - `repo
+```python
+from servai import ai_call
+
+result = ai_call(
+    github_token="ghp_...",
+    prompt="explain recursion in simple terms",
+)
+
+print(result)
+```
+
+That's it. On first run, `servai` will:
+- Create a repo called `servai-runner` on your GitHub account
+- Set up the workflow automatically
+- Download and cache TinyLlama 1.1B (~0.6 GB)
+
+Subsequent calls reuse the cached repo and model.
+
+---
+
+## Examples
+
+**Basic question**
+```python
+from servai import ai_call
+
+result = ai_call(
+    github_token="ghp_...",
+    prompt="what is the difference between a list and a tuple in Python?",
+)
+print(result)
+```
+
+**Custom system prompt**
+```python
+result = ai_call(
+    github_token="ghp_...",
+    prompt="explain black holes",
+    system="You are a physics professor. Be precise and use analogies.",
+    model="llama",
+    max_tokens=1024,
+)
+print(result)
+```
+
+**Deterministic output (temperature=0)**
+```python
+result = ai_call(
+    github_token="ghp_...",
+    prompt="what is 144 divided by 12?",
+    temperature=0.0,
+    max_tokens=16,
+)
+print(result)  # always returns the same answer
+```
+
+**Silent mode (no logs)**
+```python
+result = ai_call(
+    github_token="ghp_...",
+    prompt="summarize the theory of evolution",
+    verbose=False,
+)
+print(result)
+```
+
+**Large output**
+```python
+result = ai_call(
+    github_token="ghp_...",
+    prompt="write a detailed essay on the causes of World War I",
+    max_tokens=2048,
+    temperature=0.5,
+    model="llama",
+)
+print(result)
+```
+
+**Multiple calls in sequence**
+```python
+from servai import ai_call
+
+TOKEN = "ghp_..."
+
+questions = [
+    "what is a neural network?",
+    "what is gradient descent?",
+    "what is backpropagation?",
+]
+
+for q in questions:
+    answer = ai_call(github_token=TOKEN, prompt=q, verbose=False)
+    print(f"Q: {q}\nA: {answer}\n")
+```
+
+**Parallel calls (use separate repo per call)**
+```python
+import threading
+from servai import ai_call
+
+TOKEN = "ghp_..."
+results = {}
+
+def run(key, prompt, repo):
+    results[key] = ai_call(
+        github_token=TOKEN,
+        prompt=prompt,
+        repo_name=repo,
+        verbose=False,
+    )
+
+t1 = threading.Thread(target=run, args=("q1", "explain DNA", "servai-repo-1"))
+t2 = threading.Thread(target=run, args=("q2", "explain RNA", "servai-repo-2"))
+
+t1.start(); t2.start()
+t1.join();  t2.join()
+
+print(results["q1"])
+print(results["q2"])
+```
+
+> **Note:** Parallel calls must use different `repo_name` values. Each repo has its own independent run queue, so calls never interfere with each other.
+
+---
+
+## Parameters
+
+| Parameter | Type | Default | Required | Description |
+|---|---|---|---|---|
+| `github_token` | `str` | — | Yes | GitHub PAT with `repo` and `workflow` scopes |
+| `prompt` | `str` | — | Yes | The message or question to send to the model |
+| `model` | `str` | `"tinyllama"` | No | Which model to use. See Models section below |
+| `system` | `str` | `"You are a helpful assistant."` | No | System prompt that controls model behavior |
+| `max_tokens` | `int` | `512` | No | Max tokens to generate. Hard limit: 4096 |
+| `temperature` | `float` | `0.7` | No | Randomness. `0.0` = deterministic, `2.0` = very creative |
+| `cache` | `bool` | `True` | No | Cache model weights between runs. Strongly recommended |
+| `n_ctx` | `int` | `None` | No | Context window size. Defaults to model built-in. Max: 8192 |
+| `repo_name` | `str` | `"servai-runner"` | No | GitHub repo to create or reuse for running inference |
+| `verbose` | `bool` | `True` | No | Print step-by-step logs. Set `False` for silent mode |
+
+---
+
+## Models
+
+| Key | Model | Size | Default Context | Max Safe Context |
+|---|---|---|---|---|
+| `tinyllama` | TinyLlama 1.1B Chat Q4_K_M | 0.6 GB | 2048 tokens | 8192 tokens |
+| `llama` | Llama 3.2 1B Instruct Q4_K_M | 0.7 GB | 4096 tokens | 8192 tokens |
+
+Both models are quantized GGUF files hosted publicly on HuggingFace. No HuggingFace token required.
+
+**Which model should I use?**
+- `tinyllama` — faster, smaller, good for short factual answers and simple tasks
+- `llama` — better instruction-following, better for longer structured outputs and reasoning
+
+---
+
+## Context and output size
+
+The context window (`n_ctx`) is the total number of tokens the model can see at once — this includes your system prompt, your prompt, and the generated output combined.

gh_ai_runner-0.1.3/README.md

@@ -0,0 +1,214 @@
+# Servai
+
+[![PyPI version](https://badge.fury.io/py/servai.svg)](https://badge.fury.io/py/servai)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+
+**Serverless AI inference via GitHub Actions. No server. No GPU. No infrastructure.**
+
+Run open-source LLMs directly through GitHub's free CI/CD runners — just a GitHub token and a prompt. `servai` handles everything else: repo creation, workflow setup, model downloading, caching, and output retrieval.
+
+Built by [Tanish Chauhan](https://github.com/TanishC4444)
+
+---
+
+## How it works
+
+When you call `ai_call()`:
+
+1. Creates a private GitHub repo (once, automatically)
+2. Commits a workflow + inference script into it
+3. Dispatches a `workflow_dispatch` GitHub Actions run
+4. The runner downloads and caches the model (GGUF quantized, ~0.6 GB)
+5. Runs inference via `llama-cpp-python`
+6. Uploads the output as an artifact
+7. Downloads and returns the output to you as a string
+
+No server is ever running between calls. Each call spins up a fresh GitHub Actions runner, runs inference, and shuts down.
+
+---
+
+## Install
+```bash
+pip install servai
+```
+
+**Requirements:**
+- Python 3.9+
+- A GitHub account with a personal access token (PAT)
+- Token scopes needed: `repo`, `workflow`
+
+---
+
+## Getting a GitHub Token
+
+You need a GitHub Personal Access Token (PAT) with `repo` and `workflow` scopes.
+
+**Classic token (recommended):**
+
+1. Go to [github.com/settings/tokens](https://github.com/settings/tokens)
+2. Click **Generate new token > Generate new token (classic)**
+3. Give it a name (e.g. `servai`)
+4. Set an expiration
+5. Check these scopes:
+   - `repo
+```python
+from servai import ai_call
+
+result = ai_call(
+    github_token="ghp_...",
+    prompt="explain recursion in simple terms",
+)
+
+print(result)
+```
+
+That's it. On first run, `servai` will:
+- Create a repo called `servai-runner` on your GitHub account
+- Set up the workflow automatically
+- Download and cache TinyLlama 1.1B (~0.6 GB)
+
+Subsequent calls reuse the cached repo and model.
+
+---
+
+## Examples
+
+**Basic question**
+```python
+from servai import ai_call
+
+result = ai_call(
+    github_token="ghp_...",
+    prompt="what is the difference between a list and a tuple in Python?",
+)
+print(result)
+```
+
+**Custom system prompt**
+```python
+result = ai_call(
+    github_token="ghp_...",
+    prompt="explain black holes",
+    system="You are a physics professor. Be precise and use analogies.",
+    model="llama",
+    max_tokens=1024,
+)
+print(result)
+```
+
+**Deterministic output (temperature=0)**
+```python
+result = ai_call(
+    github_token="ghp_...",
+    prompt="what is 144 divided by 12?",
+    temperature=0.0,
+    max_tokens=16,
+)
+print(result)  # always returns the same answer
+```
+
+**Silent mode (no logs)**
+```python
+result = ai_call(
+    github_token="ghp_...",
+    prompt="summarize the theory of evolution",
+    verbose=False,
+)
+print(result)
+```
+
+**Large output**
+```python
+result = ai_call(
+    github_token="ghp_...",
+    prompt="write a detailed essay on the causes of World War I",
+    max_tokens=2048,
+    temperature=0.5,
+    model="llama",
+)
+print(result)
+```
+
+**Multiple calls in sequence**
+```python
+from servai import ai_call
+
+TOKEN = "ghp_..."
+
+questions = [
+    "what is a neural network?",
+    "what is gradient descent?",
+    "what is backpropagation?",
+]
+
+for q in questions:
+    answer = ai_call(github_token=TOKEN, prompt=q, verbose=False)
+    print(f"Q: {q}\nA: {answer}\n")
+```
+
+**Parallel calls (use separate repo per call)**
+```python
+import threading
+from servai import ai_call
+
+TOKEN = "ghp_..."
+results = {}
+
+def run(key, prompt, repo):
+    results[key] = ai_call(
+        github_token=TOKEN,
+        prompt=prompt,
+        repo_name=repo,
+        verbose=False,
+    )
+
+t1 = threading.Thread(target=run, args=("q1", "explain DNA", "servai-repo-1"))
+t2 = threading.Thread(target=run, args=("q2", "explain RNA", "servai-repo-2"))
+
+t1.start(); t2.start()
+t1.join();  t2.join()
+
+print(results["q1"])
+print(results["q2"])
+```
+
+> **Note:** Parallel calls must use different `repo_name` values. Each repo has its own independent run queue, so calls never interfere with each other.
+
+---
+
+## Parameters
+
+| Parameter | Type | Default | Required | Description |
+|---|---|---|---|---|
+| `github_token` | `str` | — | Yes | GitHub PAT with `repo` and `workflow` scopes |
+| `prompt` | `str` | — | Yes | The message or question to send to the model |
+| `model` | `str` | `"tinyllama"` | No | Which model to use. See Models section below |
+| `system` | `str` | `"You are a helpful assistant."` | No | System prompt that controls model behavior |
+| `max_tokens` | `int` | `512` | No | Max tokens to generate. Hard limit: 4096 |
+| `temperature` | `float` | `0.7` | No | Randomness. `0.0` = deterministic, `2.0` = very creative |
+| `cache` | `bool` | `True` | No | Cache model weights between runs. Strongly recommended |
+| `n_ctx` | `int` | `None` | No | Context window size. Defaults to model built-in. Max: 8192 |
+| `repo_name` | `str` | `"servai-runner"` | No | GitHub repo to create or reuse for running inference |
+| `verbose` | `bool` | `True` | No | Print step-by-step logs. Set `False` for silent mode |
+
+---
+
+## Models
+
+| Key | Model | Size | Default Context | Max Safe Context |
+|---|---|---|---|---|
+| `tinyllama` | TinyLlama 1.1B Chat Q4_K_M | 0.6 GB | 2048 tokens | 8192 tokens |
+| `llama` | Llama 3.2 1B Instruct Q4_K_M | 0.7 GB | 4096 tokens | 8192 tokens |
+
+Both models are quantized GGUF files hosted publicly on HuggingFace. No HuggingFace token required.
+
+**Which model should I use?**
+- `tinyllama` — faster, smaller, good for short factual answers and simple tasks
+- `llama` — better instruction-following, better for longer structured outputs and reasoning
+
+---
+
+## Context and output size
+
+The context window (`n_ctx`) is the total number of tokens the model can see at once — this includes your system prompt, your prompt, and the generated output combined.

gh_ai_runner-0.1.3/gh_ai_runner.egg-info/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: gh-ai-runner
+Version: 0.1.3
+Summary: Serverless AI inference via GitHub Actions — no server required
+Author: Tanish Chauhan
+License: MIT
+Project-URL: Homepage, https://github.com/TanishC4444/servai
+Project-URL: Repository, https://github.com/TanishC4444/servai
+Keywords: ai,llm,inference,github-actions,llama,serverless
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# Servai
+
+[![PyPI version](https://badge.fury.io/py/servai.svg)](https://badge.fury.io/py/servai)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+
+**Serverless AI inference via GitHub Actions. No server. No GPU. No infrastructure.**
+
+Run open-source LLMs directly through GitHub's free CI/CD runners — just a GitHub token and a prompt. `servai` handles everything else: repo creation, workflow setup, model downloading, caching, and output retrieval.
+
+Built by [Tanish Chauhan](https://github.com/TanishC4444)
+
+---
+
+## How it works
+
+When you call `ai_call()`:
+
+1. Creates a private GitHub repo (once, automatically)
+2. Commits a workflow + inference script into it
+3. Dispatches a `workflow_dispatch` GitHub Actions run
+4. The runner downloads and caches the model (GGUF quantized, ~0.6 GB)
+5. Runs inference via `llama-cpp-python`
+6. Uploads the output as an artifact
+7. Downloads and returns the output to you as a string
+
+No server is ever running between calls. Each call spins up a fresh GitHub Actions runner, runs inference, and shuts down.
+
+---
+
+## Install
+```bash
+pip install servai
+```
+
+**Requirements:**
+- Python 3.9+
+- A GitHub account with a personal access token (PAT)
+- Token scopes needed: `repo`, `workflow`
+
+---
+
+## Getting a GitHub Token
+
+You need a GitHub Personal Access Token (PAT) with `repo` and `workflow` scopes.
+
+**Classic token (recommended):**
+
+1. Go to [github.com/settings/tokens](https://github.com/settings/tokens)
+2. Click **Generate new token > Generate new token (classic)**
+3. Give it a name (e.g. `servai`)
+4. Set an expiration
+5. Check these scopes:
+   - `repo
+```python
+from servai import ai_call
+
+result = ai_call(
+    github_token="ghp_...",
+    prompt="explain recursion in simple terms",
+)
+
+print(result)
+```
+
+That's it. On first run, `servai` will:
+- Create a repo called `servai-runner` on your GitHub account
+- Set up the workflow automatically
+- Download and cache TinyLlama 1.1B (~0.6 GB)
+
+Subsequent calls reuse the cached repo and model.
+
+---
+
+## Examples
+
+**Basic question**
+```python
+from servai import ai_call
+
+result = ai_call(
+    github_token="ghp_...",
+    prompt="what is the difference between a list and a tuple in Python?",
+)
+print(result)
+```
+
+**Custom system prompt**
+```python
+result = ai_call(
+    github_token="ghp_...",
+    prompt="explain black holes",
+    system="You are a physics professor. Be precise and use analogies.",
+    model="llama",
+    max_tokens=1024,
+)
+print(result)
+```
+
+**Deterministic output (temperature=0)**
+```python
+result = ai_call(
+    github_token="ghp_...",
+    prompt="what is 144 divided by 12?",
+    temperature=0.0,
+    max_tokens=16,
+)
+print(result)  # always returns the same answer
+```
+
+**Silent mode (no logs)**
+```python
+result = ai_call(
+    github_token="ghp_...",
+    prompt="summarize the theory of evolution",
+    verbose=False,
+)
+print(result)
+```
+
+**Large output**
+```python
+result = ai_call(
+    github_token="ghp_...",
+    prompt="write a detailed essay on the causes of World War I",
+    max_tokens=2048,
+    temperature=0.5,
+    model="llama",
+)
+print(result)
+```
+
+**Multiple calls in sequence**
+```python
+from servai import ai_call
+
+TOKEN = "ghp_..."
+
+questions = [
+    "what is a neural network?",
+    "what is gradient descent?",
+    "what is backpropagation?",
+]
+
+for q in questions:
+    answer = ai_call(github_token=TOKEN, prompt=q, verbose=False)
+    print(f"Q: {q}\nA: {answer}\n")
+```
+
+**Parallel calls (use separate repo per call)**
+```python
+import threading
+from servai import ai_call
+
+TOKEN = "ghp_..."
+results = {}
+
+def run(key, prompt, repo):
+    results[key] = ai_call(
+        github_token=TOKEN,
+        prompt=prompt,
+        repo_name=repo,
+        verbose=False,
+    )
+
+t1 = threading.Thread(target=run, args=("q1", "explain DNA", "servai-repo-1"))
+t2 = threading.Thread(target=run, args=("q2", "explain RNA", "servai-repo-2"))
+
+t1.start(); t2.start()
+t1.join();  t2.join()
+
+print(results["q1"])
+print(results["q2"])
+```
+
+> **Note:** Parallel calls must use different `repo_name` values. Each repo has its own independent run queue, so calls never interfere with each other.
+
+---
+
+## Parameters
+
+| Parameter | Type | Default | Required | Description |
+|---|---|---|---|---|
+| `github_token` | `str` | — | Yes | GitHub PAT with `repo` and `workflow` scopes |
+| `prompt` | `str` | — | Yes | The message or question to send to the model |
+| `model` | `str` | `"tinyllama"` | No | Which model to use. See Models section below |
+| `system` | `str` | `"You are a helpful assistant."` | No | System prompt that controls model behavior |
+| `max_tokens` | `int` | `512` | No | Max tokens to generate. Hard limit: 4096 |
+| `temperature` | `float` | `0.7` | No | Randomness. `0.0` = deterministic, `2.0` = very creative |
+| `cache` | `bool` | `True` | No | Cache model weights between runs. Strongly recommended |
+| `n_ctx` | `int` | `None` | No | Context window size. Defaults to model built-in. Max: 8192 |
+| `repo_name` | `str` | `"servai-runner"` | No | GitHub repo to create or reuse for running inference |
+| `verbose` | `bool` | `True` | No | Print step-by-step logs. Set `False` for silent mode |
+
+---
+
+## Models
+
+| Key | Model | Size | Default Context | Max Safe Context |
+|---|---|---|---|---|
+| `tinyllama` | TinyLlama 1.1B Chat Q4_K_M | 0.6 GB | 2048 tokens | 8192 tokens |
+| `llama` | Llama 3.2 1B Instruct Q4_K_M | 0.7 GB | 4096 tokens | 8192 tokens |
+
+Both models are quantized GGUF files hosted publicly on HuggingFace. No HuggingFace token required.
+
+**Which model should I use?**
+- `tinyllama` — faster, smaller, good for short factual answers and simple tasks
+- `llama` — better instruction-following, better for longer structured outputs and reasoning
+
+---
+
+## Context and output size
+
+The context window (`n_ctx`) is the total number of tokens the model can see at once — this includes your system prompt, your prompt, and the generated output combined.

gh_ai_runner-0.1.3/gh_ai_runner.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+gh_ai_runner.egg-info/PKG-INFO
+gh_ai_runner.egg-info/SOURCES.txt
+gh_ai_runner.egg-info/dependency_links.txt
+gh_ai_runner.egg-info/requires.txt
+gh_ai_runner.egg-info/top_level.txt
+servai/__init__.py
+servai/artifact.py
+servai/core.py
+servai/logger.py
+servai/models.py
+servai/polling.py
+servai/repo.py
+servai/runner.py
+servai/validation.py

gh_ai_runner-0.1.3/gh_ai_runner.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

gh_ai_runner-0.1.3/gh_ai_runner.egg-info/requires.txt

@@ -0,0 +1,4 @@
+requests>=2.28
+
+[dev]
+pytest

gh_ai_runner-0.1.3/gh_ai_runner.egg-info/top_level.txt

@@ -0,0 +1 @@
+servai

gh_ai_runner-0.1.3/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gh-ai-runner"
+version = "0.1.3"
+description = "Serverless AI inference via GitHub Actions — no server required"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "Tanish Chauhan" }]
+keywords = ["ai", "llm", "inference", "github-actions", "llama", "serverless"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = ["requests>=2.28"]
+
+[project.urls]
+Homepage = "https://github.com/TanishC4444/servai"
+Repository = "https://github.com/TanishC4444/servai"
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["servai*"]

gh_ai_runner-0.1.3/servai/__init__.py

@@ -0,0 +1,5 @@
+from .core import ai_call
+from .models import MODELS, MAX_TOKENS_LIMIT, MAX_TEMPERATURE, MIN_TEMPERATURE
+
+__version__ = "0.1.3"
+__all__ = ["ai_call", "MODELS", "MAX_TOKENS_LIMIT", "MAX_TEMPERATURE", "MIN_TEMPERATURE"]

gh_ai_runner-0.1.3/servai/artifact.py

@@ -0,0 +1,44 @@
+import io
+import time
+import zipfile
+
+import requests
+
+from .logger import _log
+from .repo import API, _headers
+
+
+def _download_output(token, username, repo_name, run_id, verbose, timeout=60):
+    start  = time.time()
+    target = None
+
+    while time.time() - start < timeout:
+        r         = requests.get(
+            f"{API}/repos/{username}/{repo_name}/actions/runs/{run_id}/artifacts",
+            headers=_headers(token),
+        )
+        artifacts = r.json().get("artifacts", [])
+        target    = next((a for a in artifacts if a["name"] == "ai-output"), None)
+        if target:
+            break
+        _log("Waiting for artifact...", verbose=verbose)
+        time.sleep(5)
+
+    if not target:
+        raise RuntimeError("No ai-output artifact found after waiting.")
+
+    r = requests.get(
+        f"{API}/repos/{username}/{repo_name}/actions/artifacts/{target['id']}/zip",
+        headers=_headers(token),
+        allow_redirects=False,
+    )
+    location  = r.headers.get("Location", "")
+    zip_bytes = requests.get(location).content if location else r.content
+
+    with zipfile.ZipFile(io.BytesIO(zip_bytes)) as z:
+        _log(f"Artifact contents: {z.namelist()}", verbose=verbose)
+        name = next((n for n in z.namelist() if n.endswith("output.txt")), None)
+        if not name:
+            raise RuntimeError(f"output.txt not found in artifact. Contents: {z.namelist()}")
+        with z.open(name) as f:
+            return f.read().decode()

gh_ai_runner-0.1.3/servai/core.py

@@ -0,0 +1,112 @@
+import time
+
+import requests
+
+from .artifact import _download_output
+from .logger import _elapsed, _log
+from .models import MODELS, RAM_PER_1K_CTX_GB, RUNNER_RAM_GB
+from .polling import _snapshot_run_ids, _wait_for_completion, _wait_for_run
+from .repo import API, _ensure_repo, _get_username, _headers, _sync_files
+from .validation import _validate
+
+
+def ai_call(
+    github_token: str,
+    prompt:       str,
+    model:        str   = "tinyllama",
+    system:       str   = "You are a helpful assistant.",
+    max_tokens:   int   = 512,
+    temperature:  float = 0.7,
+    cache:        bool  = True,
+    n_ctx:        int   = None,
+    repo_name:    str   = "ai-inference-runner",
+    verbose:      bool  = True,
+) -> str:
+    """
+    Run AI inference on GitHub Actions and return the model output.
+
+    Required:
+        github_token: Your GitHub personal access token (needs repo + workflow scopes).
+        prompt:       The message / question to send to the model.
+
+    Optional:
+        model:        "tinyllama" (default) or "llama".
+        system:       System prompt. Default: "You are a helpful assistant."
+        max_tokens:   Max tokens to generate. Default: 512. Hard limit: 4096.
+        temperature:  0.0 = deterministic, 2.0 = very creative. Default: 0.7.
+        cache:        Cache model weights between runs. Default: True.
+        n_ctx:        Context window size. Default: 2048 (tinyllama) / 4096 (llama). Max: 8192.
+        repo_name:    GitHub repo to create/reuse. Default: "ai-inference-runner".
+        verbose:      Print detailed logs. Default: True. Set False for silent mode.
+
+    Returns:
+        Model response as a string.
+
+    Raises:
+        ValueError: If any parameter is out of safe range.
+    """
+    if model not in MODELS:
+        raise ValueError(f"model must be one of: {list(MODELS.keys())}")
+
+    _validate(model, max_tokens, temperature, n_ctx)
+
+    call_start      = time.time()
+    cfg             = MODELS[model]
+    username        = _get_username(github_token)
+    effective_n_ctx = n_ctx or cfg["n_ctx"]
+    extra_ctx       = max(0, effective_n_ctx - cfg["n_ctx"])
+    est_ram         = cfg["size_gb"] + (extra_ctx / 1000) * RAM_PER_1K_CTX_GB + 1.0
+
+    _log("=" * 50,                                                                 verbose=verbose)
+    _log("ai_call started",                                                        verbose=verbose)
+    _log(f"Model      : {cfg['name']} ({cfg['size_gb']} GB GGUF)",                verbose=verbose)
+    _log(f"n_ctx      : {effective_n_ctx}  |  Est. RAM: {est_ram:.1f} GB",        verbose=verbose)
+    _log(f"Max tokens : {max_tokens}  |  Temp: {temperature}  |  Cache: {cache}", verbose=verbose)
+    _log(f"Prompt     : {prompt[:80]}{'...' if len(prompt) > 80 else ''}",        verbose=verbose)
+    _log("=" * 50,                                                                 verbose=verbose)
+
+    _ensure_repo(github_token, username, repo_name, verbose)
+    _sync_files(github_token, username, repo_name, verbose)
+
+    seen_ids = _snapshot_run_ids(github_token, username, repo_name)
+
+    t = time.time()
+    _log("Dispatching workflow...", verbose=verbose)
+    r = requests.post(
+        f"{API}/repos/{username}/{repo_name}/actions/workflows/inference.yml/dispatches",
+        headers=_headers(github_token),
+        json={
+            "ref": "main",
+            "inputs": {
+                "prompt":      prompt,
+                "system":      system,
+                "model":       model,
+                "cache":       "true" if cache else "false",
+                "max_tokens":  str(max_tokens),
+                "temperature": str(temperature),
+                "n_ctx":       str(n_ctx) if n_ctx else "",
+            },
+        },
+    )
+    r.raise_for_status()
+    _log("Workflow dispatched", since=t, verbose=verbose)
+
+    t = time.time()
+    _log("Waiting for runner...", verbose=verbose)
+    run_id = _wait_for_run(github_token, username, repo_name, seen_ids, verbose)
+
+    t = time.time()
+    _log("Runner working (first run ~5 min, cached ~1-2 min)...", verbose=verbose)
+    _wait_for_completion(github_token, username, repo_name, run_id, verbose)
+    _log("Runner finished", since=t, verbose=verbose)
+
+    t = time.time()
+    _log("Downloading output...", verbose=verbose)
+    output = _download_output(github_token, username, repo_name, run_id, verbose)
+    _log("Output downloaded", since=t, verbose=verbose)
+
+    _log("=" * 50,                               verbose=verbose)
+    _log(f"Total time : {_elapsed(call_start)}", verbose=verbose)
+    _log("=" * 50,                               verbose=verbose)
+
+    return output

gh_ai_runner-0.1.3/servai/logger.py

@@ -0,0 +1,17 @@
+import time
+from datetime import datetime
+
+
+def _ts():
+    return datetime.now().strftime("%H:%M:%S")
+
+
+def _elapsed(since):
+    return f"{time.time() - since:.1f}s"
+
+
+def _log(msg, since=None, verbose=True):
+    if not verbose:
+        return
+    suffix = f"  (+{_elapsed(since)})" if since else ""
+    print(f"[{_ts()}] {msg}{suffix}", flush=True)

gh_ai_runner-0.1.3/servai/models.py

@@ -0,0 +1,24 @@
+MODELS = {
+    "tinyllama": {
+        "name":      "TinyLlama 1.1B Chat",
+        "size_gb":   0.6,
+        "n_ctx":     2048,
+        "max_n_ctx": 8192,
+        "url":       "https://huggingface.co/TheBloke/TinyLlama-1.1B-Chat-v1.0-GGUF/resolve/main/tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf",
+        "filename":  "tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf",
+    },
+    "llama": {
+        "name":      "Llama 3.2 1B Instruct",
+        "size_gb":   0.7,
+        "n_ctx":     4096,
+        "max_n_ctx": 8192,
+        "url":       "https://huggingface.co/bartowski/Llama-3.2-1B-Instruct-GGUF/resolve/main/Llama-3.2-1B-Instruct-Q4_K_M.gguf",
+        "filename":  "Llama-3.2-1B-Instruct-Q4_K_M.gguf",
+    },
+}
+
+RUNNER_RAM_GB     = 7
+RAM_PER_1K_CTX_GB = 0.2
+MAX_TOKENS_LIMIT  = 4096
+MAX_TEMPERATURE   = 2.0
+MIN_TEMPERATURE   = 0.0

gh_ai_runner-0.1.3/servai/polling.py

@@ -0,0 +1,60 @@
+import time
+
+import requests
+
+from .logger import _log
+from .repo import API, _headers
+
+
+def _snapshot_run_ids(token, username, repo_name):
+    r = requests.get(
+        f"{API}/repos/{username}/{repo_name}/actions/runs",
+        headers=_headers(token),
+        params={"per_page": 20},
+    )
+    return {run["id"] for run in r.json().get("workflow_runs", [])}
+
+
+def _wait_for_run(token, username, repo_name, seen_ids, verbose, timeout=180):
+    start = time.time()
+    while time.time() - start < timeout:
+        time.sleep(4)
+        r = requests.get(
+            f"{API}/repos/{username}/{repo_name}/actions/runs",
+            headers=_headers(token),
+            params={"per_page": 10},
+        )
+        for run in r.json().get("workflow_runs", []):
+            if run["id"] not in seen_ids:
+                _log(f"Runner picked up job (run #{run['id']})", verbose=verbose)
+                return run["id"]
+    raise TimeoutError("Timed out waiting for workflow run to appear.")
+
+
+def _wait_for_completion(token, username, repo_name, run_id, verbose, timeout=900, poll=12):
+    start       = time.time()
+    last_status = None
+    while time.time() - start < timeout:
+        r          = requests.get(
+            f"{API}/repos/{username}/{repo_name}/actions/runs/{run_id}",
+            headers=_headers(token),
+        )
+        data       = r.json()
+        status     = data["status"]
+        conclusion = data.get("conclusion")
+
+        if status != last_status:
+            _log(f"Runner: {status}{' -> ' + conclusion if conclusion else ''}",
+                 verbose=verbose)
+            last_status = status
+
+        if status == "completed":
+            if conclusion != "success":
+                raise RuntimeError(
+                    f"Workflow failed ({conclusion}) — "
+                    f"https://github.com/{username}/{repo_name}/actions/runs/{run_id}"
+                )
+            return
+
+        time.sleep(poll)
+    raise TimeoutError("Timed out waiting for workflow to complete.")

gh_ai_runner-0.1.3/servai/repo.py

@@ -0,0 +1,85 @@
+import base64
+import time
+
+import requests
+
+from .logger import _log
+from .runner import INFERENCE_SCRIPT, WORKFLOW_YAML
+
+API = "https://api.github.com"
+
+
+def _headers(token):
+    return {
+        "Authorization": f"token {token}",
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+    }
+
+
+def _get_username(token):
+    r = requests.get(f"{API}/user", headers=_headers(token))
+    r.raise_for_status()
+    return r.json()["login"]
+
+
+def _repo_exists(token, username, repo_name):
+    return requests.get(
+        f"{API}/repos/{username}/{repo_name}", headers=_headers(token)
+    ).status_code == 200
+
+
+def _commit_file(token, username, repo_name, path, content, message):
+    url      = f"{API}/repos/{username}/{repo_name}/contents/{path}"
+    existing = requests.get(url, headers=_headers(token))
+    sha      = existing.json().get("sha") if existing.status_code == 200 else None
+    body     = {"message": message, "content": base64.b64encode(content.encode()).decode()}
+    if sha:
+        body["sha"] = sha
+    requests.put(url, headers=_headers(token), json=body).raise_for_status()
+
+
+def _wait_for_workflow(token, username, repo_name, timeout=60):
+    start = time.time()
+    while time.time() - start < timeout:
+        r         = requests.get(
+            f"{API}/repos/{username}/{repo_name}/actions/workflows",
+            headers=_headers(token),
+        )
+        workflows = r.json().get("workflows", [])
+        if any(w["path"] == ".github/workflows/inference.yml" for w in workflows):
+            return
+        time.sleep(3)
+    raise TimeoutError("Workflow never registered.")
+
+
+def _ensure_repo(token, username, repo_name, verbose):
+    if _repo_exists(token, username, repo_name):
+        _log("Repo ready", verbose=verbose)
+        return
+
+    t = time.time()
+    _log("Creating repo...", verbose=verbose)
+    r = requests.post(f"{API}/user/repos", headers=_headers(token), json={
+        "name": repo_name, "private": False, "auto_init": True,
+        "description": "GitHub AI Inference Runner",
+    })
+    r.raise_for_status()
+    time.sleep(2)
+
+    _commit_file(token, username, repo_name,
+                 "run_inference.py", INFERENCE_SCRIPT, "Add inference script")
+    _commit_file(token, username, repo_name,
+                 ".github/workflows/inference.yml", WORKFLOW_YAML, "Add inference workflow")
+
+    _wait_for_workflow(token, username, repo_name)
+    _log("Repo created and ready", since=t, verbose=verbose)
+
+
+def _sync_files(token, username, repo_name, verbose):
+    _log("Syncing runner files...", verbose=verbose)
+    _commit_file(token, username, repo_name,
+                 "run_inference.py", INFERENCE_SCRIPT, "Sync inference script")
+    _commit_file(token, username, repo_name,
+                 ".github/workflows/inference.yml", WORKFLOW_YAML, "Sync workflow")
+    _log("Runner files synced", verbose=verbose)

gh_ai_runner-0.1.3/servai/runner.py

@@ -0,0 +1,116 @@
+INFERENCE_SCRIPT = r'''
+import os, urllib.request, warnings
+warnings.filterwarnings("ignore")
+from llama_cpp import Llama
+
+MODEL_MAP = {
+    "tinyllama": {
+        "url":      "https://huggingface.co/TheBloke/TinyLlama-1.1B-Chat-v1.0-GGUF/resolve/main/tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf",
+        "filename": "tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf",
+        "n_ctx":    2048,
+    },
+    "llama": {
+        "url":      "https://huggingface.co/bartowski/Llama-3.2-1B-Instruct-GGUF/resolve/main/Llama-3.2-1B-Instruct-Q4_K_M.gguf",
+        "filename": "Llama-3.2-1B-Instruct-Q4_K_M.gguf",
+        "n_ctx":    4096,
+    },
+}
+
+model_key   = os.environ["MODEL"]
+prompt      = os.environ["PROMPT"]
+system      = os.environ.get("SYSTEM", "You are a helpful assistant.")
+max_tokens  = int(os.environ.get("MAX_TOKENS", "512"))
+temperature = float(os.environ.get("TEMPERATURE", "0.7"))
+n_ctx_env   = os.environ.get("N_CTX", "").strip()
+
+cfg        = MODEL_MAP[model_key]
+n_ctx      = int(n_ctx_env) if n_ctx_env else cfg["n_ctx"]
+model_path = f"model_cache/{cfg['filename']}"
+
+if not os.path.exists(model_path):
+    os.makedirs("model_cache", exist_ok=True)
+    print(f"Downloading {cfg['filename']}...")
+    urllib.request.urlretrieve(cfg["url"], model_path)
+
+print(f"Loading {cfg['filename']} (n_ctx={n_ctx})...")
+llm = Llama(model_path=model_path, n_ctx=n_ctx, n_threads=4, verbose=False)
+
+print("Running inference...")
+response = llm.create_chat_completion(
+    messages=[
+        {"role": "system", "content": system},
+        {"role": "user",   "content": prompt},
+    ],
+    max_tokens=max_tokens,
+    temperature=temperature,
+)
+
+output = response["choices"][0]["message"]["content"]
+print("\n=== OUTPUT ===")
+print(output)
+
+with open("output.txt", "w") as f:
+    f.write(output)
+'''
+
+WORKFLOW_YAML = """\
+name: AI Inference
+on:
+  workflow_dispatch:
+    inputs:
+      prompt:      { description: "User prompt",     required: true  }
+      system:      { description: "System prompt",   required: false, default: "You are a helpful assistant." }
+      model:       { description: "tinyllama|llama", required: false, default: "tinyllama" }
+      cache:       { description: "Cache weights",   required: false, default: "true" }
+      max_tokens:  { description: "Max new tokens",  required: false, default: "512" }
+      temperature: { description: "Temperature",     required: false, default: "0.7" }
+      n_ctx:       { description: "Context window",  required: false, default: "" }
+
+jobs:
+  inference:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Cache venv
+        id: cache-venv
+        uses: actions/cache@v4
+        with:
+          path: .venv
+          key: venv-llama-cpp-v1
+
+      - name: Cache model weights
+        if: ${{ inputs.cache == 'true' }}
+        uses: actions/cache@v4
+        with:
+          path: model_cache
+          key: gguf-${{ inputs.model }}-v1
+
+      - name: Install dependencies
+        if: steps.cache-venv.outputs.cache-hit != 'true'
+        run: |
+          python -m venv .venv
+          CMAKE_ARGS="-DGGML_METAL=off" .venv/bin/pip install llama-cpp-python -q
+
+      - name: Run inference
+        env:
+          PROMPT:      ${{ inputs.prompt }}
+          SYSTEM:      ${{ inputs.system }}
+          MODEL:       ${{ inputs.model }}
+          MAX_TOKENS:  ${{ inputs.max_tokens }}
+          TEMPERATURE: ${{ inputs.temperature }}
+          N_CTX:       ${{ inputs.n_ctx }}
+        run: .venv/bin/python run_inference.py
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: ai-output
+          path: output.txt
+          retention-days: 1
+"""

gh_ai_runner-0.1.3/servai/validation.py

@@ -0,0 +1,51 @@
+from .models import (
+    MODELS,
+    RUNNER_RAM_GB,
+    RAM_PER_1K_CTX_GB,
+    MAX_TOKENS_LIMIT,
+    MAX_TEMPERATURE,
+    MIN_TEMPERATURE,
+)
+
+
+def _validate(model, max_tokens, temperature, n_ctx):
+    cfg    = MODELS[model]
+    errors = []
+
+    if not (MIN_TEMPERATURE <= temperature <= MAX_TEMPERATURE):
+        errors.append(
+            f"temperature must be between {MIN_TEMPERATURE} and {MAX_TEMPERATURE}, got {temperature}"
+        )
+
+    if max_tokens < 1:
+        errors.append(f"max_tokens must be at least 1, got {max_tokens}")
+    if max_tokens > MAX_TOKENS_LIMIT:
+        errors.append(f"max_tokens={max_tokens} exceeds hard limit of {MAX_TOKENS_LIMIT}.")
+
+    effective_n_ctx = n_ctx or cfg["n_ctx"]
+    if effective_n_ctx > cfg["max_n_ctx"]:
+        errors.append(
+            f"n_ctx={effective_n_ctx} exceeds safe limit of {cfg['max_n_ctx']}. Risk of OOM."
+        )
+    if max_tokens >= effective_n_ctx:
+        errors.append(
+            f"max_tokens={max_tokens} must be less than n_ctx={effective_n_ctx}."
+        )
+
+    base_ram  = cfg["size_gb"]
+    extra_ctx = max(0, effective_n_ctx - cfg["n_ctx"])
+    total_ram = base_ram + (extra_ctx / 1000) * RAM_PER_1K_CTX_GB + 1.0
+    if total_ram > RUNNER_RAM_GB:
+        errors.append(
+            f"Estimated RAM ({total_ram:.1f} GB) exceeds runner limit ({RUNNER_RAM_GB} GB)."
+        )
+
+    if errors:
+        raise ValueError("Validation failed:\n" + "\n".join(f"  - {e}" for e in errors))
+
+    if max_tokens > 2048:
+        print(f"[warn] max_tokens={max_tokens} is large — expect slower inference.")
+    if effective_n_ctx > 4096:
+        print(f"[warn] n_ctx={effective_n_ctx} is large — estimated RAM: {total_ram:.1f} GB.")
+    if temperature > 1.2:
+        print(f"[warn] temperature={temperature} is high — output may be incoherent.")

gh_ai_runner-0.1.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+