maur 0.1.0__tar.gz

maur-0.1.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.3
+Name: maur
+Version: 0.1.0
+Summary: Add your description here
+Author: Mats E. Mollestad
+Author-email: Mats E. Mollestad <mats@mollestad.no>
+Requires-Dist: fastapi
+Requires-Dist: sqlalchemy[asyncio]
+Requires-Dist: sqlmodel
+Requires-Dist: takk>=0.1.25
+Requires-Dist: asyncpg
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Maur 🐜
+
+Inspired by [Strip's Minions](https://stripe.dev/blog/minions-stripes-one-shot-end-to-end-coding-agents). Maur (Norwegian for "ants") is an autonomous coding agent that integrates into your Python projects. It receives tasks from various sources — production error alerts, Slack, Linear issues, or direct API calls — clones your repo, runs an AI coding agent ([OpenCode](https://opencode.ai)), and opens a pull/merge request with the fix.
+
+## How it works
+
+1. A task arrives via webhook or direct API call
+2. The API stores the task and publishes it to a message queue
+3. A worker picks up the task, clones your repo into a temporary workspace
+4. OpenCode runs against the cloned repo using your configured LLM
+5. If changes are made, they are committed and pushed to a new branch (`maur/<task-id>`)
+6. A pull request (GitHub) or merge request (GitLab) is opened automatically
+
+## Architecture
+
+```
+[Trigger source]           [maur_api]          [maur_code_subscriber]
+  Linear webhook    --->   FastAPI app   --->   Worker (OpenCode)
+  Exception alert          stores task          clones repo
+  Manual POST /tasks       publishes msg        runs agent
+                                                opens PR/MR
+```
+
+The two components are deployed separately via `takk`:
+- **`maur_api`** — lightweight FastAPI service that authenticates requests, persists tasks, and enqueues work
+- **`maur_code_subscriber`** — NATS subscriber that processes tasks one at a time using OpenCode
+
+## Prerequisites
+
+- Python ≥ 3.10
+- [`takk`](https://pypi.org/project/takk/) for infrastructure management
+- A NATS server (provisioned by `takk`)
+- A PostgreSQL or MySQL database (provisioned by `takk`)
+- An OpenAI-compatible LLM API (e.g. [OpenRouter](https://openrouter.ai), a local Ollama instance, or any provider with an OpenAI-compatible endpoint. `takk` default to using Ollama unless you overwrite the env vars.)
+- A GitHub or GitLab repository with a token that has push and PR/MR creation permissions
+
+## Installation
+
+```bash
+uv add maur
+```
+
+## Basic usage
+
+### 1. Add the infrastructure
+
+Add both components to your `project.py` file:
+
+```python
+from maur.components import maur_api, maur_code_subscriber
+
+project = Project(
+    name="your-project",
+
+    # The API that authenticates and enqueues tasks
+    maur_api=maur_api(),
+
+    # The worker that clones the repo, runs OpenCode, and opens a PR/MR
+    # Pass secrets for any environment variables your target repo needs at build time
+    maur_coder=maur_code_subscriber(secrets=[...]),
+)
+```
+
+### 2. Configure secrets
+
+Run `takk dotenv` to regenerate your `.env` file, then fill in the required values:
+
+| Variable | Required | Description |
+|---|---|---|
+| `DB_URI` | No | PostgreSQL (`postgresql+asyncpg://...`) or MySQL (`mysql+aiomysql://...`) connection URI |
+| `NATS_URI` | No | NATS (`nats://...`) |
+| `MAUR_BEARER_TOKEN` | Yes | Secret token used to authenticate API requests |
+| `MAUR_LLM_TOKEN` | No | API key for your LLM provider |
+| `MAUR_LLM_API` | No | Base URL of your OpenAI-compatible LLM API |
+| `MAUR_LLM_MODEL` | No | Model to use (default: `qwen3.5:4b`) |
+| `GITHUB_REPO_URL` | Yes* | HTTPS URL of the GitHub repo to clone and open PRs on |
+| `GITHUB_TOKEN` | Yes* | GitHub personal access token with `repo` scope |
+| `GITHUB_API_URL` | No | GitHub API base URL (default: `https://api.github.com`) |
+| `GITLAB_REPO_URL` | Yes* | HTTPS URL of the GitLab repo |
+| `GITLAB_TOKEN` | Yes* | GitLab personal access token with `api` scope |
+| `GITLAB_URL` | No | GitLab instance URL (default: `https://gitlab.com`) |
+
+\* Provide either the GitHub **or** GitLab set of variables. GitLab takes precedence if both are set.
+
+### 3. Start the system
+
+```bash
+takk up
+```
+
+Both the API and worker containers will be built and started.
+
+## API reference
+
+All endpoints (except `/health`) require a `Bearer` token in the `Authorization` header matching `MAUR_BEARER_TOKEN`.
+
+### POST `/tasks` — Manual task
+
+Send any arbitrary prompt to the agent.
+
+```bash
+curl -X POST http://localhost:8000/tasks \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "prompt": "Refactor the payment module to use the new Stripe SDK",
+    "source_id": "unique-identifier-for-dedup",
+    "repo_branch": "main"
+  }'
+```
+
+### POST `/webhooks/exception` — Exception alert
+
+Send a production error for the agent to fix. `fingerprint` is used for deduplication — tasks with the same fingerprint that are already pending or in progress are rejected.
+
+```bash
+curl -X POST http://localhost:8000/webhooks/exception \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "fingerprint": "KeyError-user-profile-views-42",
+    "title": "KeyError: '\''email'\'' in user_profile view",
+    "description": "Traceback (most recent call last):\n  ...",
+    "repo_branch": "main",
+    "extra": {"environment": "production", "user_id": 123}
+  }'
+```
+
+### POST `/webhooks/linear` — Linear webhook
+
+Configure a [Linear webhook](https://linear.app/docs/webhooks) to send issue events here. Maur extracts the issue title, description, and repository URL (must be attached to the issue) and opens a PR with the fix.
+
+Set the webhook URL to: `https://<your-api-host>/webhooks/linear`
+
+Optionally set `LINEAR_WEBHOOK_SECRET` in your environment to verify webhook signatures.
+
+### GET `/tasks` — List tasks
+
+Returns the 50 most recent tasks.
+
+### GET `/tasks/{task_id}` — Get task
+
+Returns the status and result of a specific task.
+
+### GET `/health`
+
+Returns `"ok"`. Used for health checks.
+
+## Customisation
+
+### Changing the LLM model
+
+Set `MAUR_LLM_MODEL` to any model available through your `MAUR_LLM_API` provider. The worker uses OpenCode with an OpenAI-compatible provider, so any model exposed via that protocol works.
+
+```
+MAUR_LLM_MODEL=devstral-2-123b-instruct-2512
+```
+
+### Adjusting worker compute resources
+
+The default worker is allocated 3 GB of memory. Override this via the `compute` argument:
+
+```python
+from takk.models import Compute
+from maur.components import maur_code_subscriber
+
+maur_coder=maur_code_subscriber(
+    compute=Compute(mb_memory_limit=1024 * 8)  # 8 GB
+)
+```
+
+### Passing additional secrets to the worker
+
+If your target repository requires environment variables at build or runtime (e.g. private package indexes), pass them through `secrets`:
+
+```python
+from maur.components import maur_code_subscriber
+from my_project.settings import MyPrivateRegistrySettings
+
+maur_coder=maur_code_subscriber(
+    secrets=[MyPrivateRegistrySettings, ...]
+)
+```
+
+## Development
+
+```bash
+# Install dependencies
+uv sync --all-groups
+
+# Lint
+uv run ruff check .
+
+# Type check
+uv run ty check
+```

maur-0.1.0/README.md

@@ -0,0 +1,196 @@
+# Maur 🐜
+
+Inspired by [Strip's Minions](https://stripe.dev/blog/minions-stripes-one-shot-end-to-end-coding-agents). Maur (Norwegian for "ants") is an autonomous coding agent that integrates into your Python projects. It receives tasks from various sources — production error alerts, Slack, Linear issues, or direct API calls — clones your repo, runs an AI coding agent ([OpenCode](https://opencode.ai)), and opens a pull/merge request with the fix.
+
+## How it works
+
+1. A task arrives via webhook or direct API call
+2. The API stores the task and publishes it to a message queue
+3. A worker picks up the task, clones your repo into a temporary workspace
+4. OpenCode runs against the cloned repo using your configured LLM
+5. If changes are made, they are committed and pushed to a new branch (`maur/<task-id>`)
+6. A pull request (GitHub) or merge request (GitLab) is opened automatically
+
+## Architecture
+
+```
+[Trigger source]           [maur_api]          [maur_code_subscriber]
+  Linear webhook    --->   FastAPI app   --->   Worker (OpenCode)
+  Exception alert          stores task          clones repo
+  Manual POST /tasks       publishes msg        runs agent
+                                                opens PR/MR
+```
+
+The two components are deployed separately via `takk`:
+- **`maur_api`** — lightweight FastAPI service that authenticates requests, persists tasks, and enqueues work
+- **`maur_code_subscriber`** — NATS subscriber that processes tasks one at a time using OpenCode
+
+## Prerequisites
+
+- Python ≥ 3.10
+- [`takk`](https://pypi.org/project/takk/) for infrastructure management
+- A NATS server (provisioned by `takk`)
+- A PostgreSQL or MySQL database (provisioned by `takk`)
+- An OpenAI-compatible LLM API (e.g. [OpenRouter](https://openrouter.ai), a local Ollama instance, or any provider with an OpenAI-compatible endpoint. `takk` default to using Ollama unless you overwrite the env vars.)
+- A GitHub or GitLab repository with a token that has push and PR/MR creation permissions
+
+## Installation
+
+```bash
+uv add maur
+```
+
+## Basic usage
+
+### 1. Add the infrastructure
+
+Add both components to your `project.py` file:
+
+```python
+from maur.components import maur_api, maur_code_subscriber
+
+project = Project(
+    name="your-project",
+
+    # The API that authenticates and enqueues tasks
+    maur_api=maur_api(),
+
+    # The worker that clones the repo, runs OpenCode, and opens a PR/MR
+    # Pass secrets for any environment variables your target repo needs at build time
+    maur_coder=maur_code_subscriber(secrets=[...]),
+)
+```
+
+### 2. Configure secrets
+
+Run `takk dotenv` to regenerate your `.env` file, then fill in the required values:
+
+| Variable | Required | Description |
+|---|---|---|
+| `DB_URI` | No | PostgreSQL (`postgresql+asyncpg://...`) or MySQL (`mysql+aiomysql://...`) connection URI |
+| `NATS_URI` | No | NATS (`nats://...`) |
+| `MAUR_BEARER_TOKEN` | Yes | Secret token used to authenticate API requests |
+| `MAUR_LLM_TOKEN` | No | API key for your LLM provider |
+| `MAUR_LLM_API` | No | Base URL of your OpenAI-compatible LLM API |
+| `MAUR_LLM_MODEL` | No | Model to use (default: `qwen3.5:4b`) |
+| `GITHUB_REPO_URL` | Yes* | HTTPS URL of the GitHub repo to clone and open PRs on |
+| `GITHUB_TOKEN` | Yes* | GitHub personal access token with `repo` scope |
+| `GITHUB_API_URL` | No | GitHub API base URL (default: `https://api.github.com`) |
+| `GITLAB_REPO_URL` | Yes* | HTTPS URL of the GitLab repo |
+| `GITLAB_TOKEN` | Yes* | GitLab personal access token with `api` scope |
+| `GITLAB_URL` | No | GitLab instance URL (default: `https://gitlab.com`) |
+
+\* Provide either the GitHub **or** GitLab set of variables. GitLab takes precedence if both are set.
+
+### 3. Start the system
+
+```bash
+takk up
+```
+
+Both the API and worker containers will be built and started.
+
+## API reference
+
+All endpoints (except `/health`) require a `Bearer` token in the `Authorization` header matching `MAUR_BEARER_TOKEN`.
+
+### POST `/tasks` — Manual task
+
+Send any arbitrary prompt to the agent.
+
+```bash
+curl -X POST http://localhost:8000/tasks \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "prompt": "Refactor the payment module to use the new Stripe SDK",
+    "source_id": "unique-identifier-for-dedup",
+    "repo_branch": "main"
+  }'
+```
+
+### POST `/webhooks/exception` — Exception alert
+
+Send a production error for the agent to fix. `fingerprint` is used for deduplication — tasks with the same fingerprint that are already pending or in progress are rejected.
+
+```bash
+curl -X POST http://localhost:8000/webhooks/exception \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "fingerprint": "KeyError-user-profile-views-42",
+    "title": "KeyError: '\''email'\'' in user_profile view",
+    "description": "Traceback (most recent call last):\n  ...",
+    "repo_branch": "main",
+    "extra": {"environment": "production", "user_id": 123}
+  }'
+```
+
+### POST `/webhooks/linear` — Linear webhook
+
+Configure a [Linear webhook](https://linear.app/docs/webhooks) to send issue events here. Maur extracts the issue title, description, and repository URL (must be attached to the issue) and opens a PR with the fix.
+
+Set the webhook URL to: `https://<your-api-host>/webhooks/linear`
+
+Optionally set `LINEAR_WEBHOOK_SECRET` in your environment to verify webhook signatures.
+
+### GET `/tasks` — List tasks
+
+Returns the 50 most recent tasks.
+
+### GET `/tasks/{task_id}` — Get task
+
+Returns the status and result of a specific task.
+
+### GET `/health`
+
+Returns `"ok"`. Used for health checks.
+
+## Customisation
+
+### Changing the LLM model
+
+Set `MAUR_LLM_MODEL` to any model available through your `MAUR_LLM_API` provider. The worker uses OpenCode with an OpenAI-compatible provider, so any model exposed via that protocol works.
+
+```
+MAUR_LLM_MODEL=devstral-2-123b-instruct-2512
+```
+
+### Adjusting worker compute resources
+
+The default worker is allocated 3 GB of memory. Override this via the `compute` argument:
+
+```python
+from takk.models import Compute
+from maur.components import maur_code_subscriber
+
+maur_coder=maur_code_subscriber(
+    compute=Compute(mb_memory_limit=1024 * 8)  # 8 GB
+)
+```
+
+### Passing additional secrets to the worker
+
+If your target repository requires environment variables at build or runtime (e.g. private package indexes), pass them through `secrets`:
+
+```python
+from maur.components import maur_code_subscriber
+from my_project.settings import MyPrivateRegistrySettings
+
+maur_coder=maur_code_subscriber(
+    secrets=[MyPrivateRegistrySettings, ...]
+)
+```
+
+## Development
+
+```bash
+# Install dependencies
+uv sync --all-groups
+
+# Lint
+uv run ruff check .
+
+# Type check
+uv run ty check
+```

maur-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "maur"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "Mats E. Mollestad", email = "mats@mollestad.no" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "fastapi",
+    "sqlalchemy[asyncio]",
+    "sqlmodel",
+    "takk>=0.1.25",
+    "asyncpg"
+]
+
+[project.scripts]
+maur = "maur:main"
+
+[build-system]
+requires = ["uv_build>=0.9.9,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "ruff>=0.15.5",
+    "ty>=0.0.21",
+]

maur-0.1.0/src/maur/api.py

@@ -0,0 +1,141 @@
+from functools import lru_cache
+import logging
+from typing import Annotated
+from fastapi.security import OAuth2PasswordBearer
+
+from fastapi import APIRouter, Depends, Header, HTTPException, Request
+from sqlmodel import select
+
+from maur.models import CodingTask, SessionDep
+from maur.settings import MaurSettings
+from maur.schemas import (
+    ExceptionPayload,
+    LinearWebhookPayload,
+    ManualTaskPayload,
+    TaskResponse,
+)
+from maur import linear as linear_client
+from maur.components import coding_tasks_pubsub, CodingTaskMessage
+
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+bearer = OAuth2PasswordBearer(tokenUrl="/api/v1/users/token")
+
+
+@lru_cache
+def maur_settings() -> MaurSettings:
+    return MaurSettings()  # type: ignore
+
+
+SettingsDep = Annotated[MaurSettings, Depends(maur_settings)]
+
+
+async def raise_on_unauthenticated(
+    token: Annotated[str, Depends(bearer)]
+) -> None:
+    settings = maur_settings()
+
+    if token != settings.maur_bearer_token.get_secret_value():
+        raise HTTPException(status_code=403)
+
+
+async def _dedup_check(session: SessionDep, source_id: str) -> CodingTask | None:
+    result = await session.exec(
+        select(CodingTask)
+        .where(CodingTask.source_id == source_id)
+        .where(CodingTask.status.in_(["pending", "in_progress"]))  # type: ignore[union-attr]
+    )
+    return result.first()
+
+
+@router.post(
+    "/webhooks/exception", 
+    dependencies=[Depends(raise_on_unauthenticated)]
+)
+async def exception_webhook(
+    payload: ExceptionPayload,
+    session: SessionDep,
+) -> TaskResponse:
+
+    existing = await _dedup_check(session, payload.fingerprint)
+    if existing:
+        raise HTTPException(
+            status_code=409,
+            detail={"message": "Task already in progress", "task_id": str(existing.id)},
+        )
+
+    prompt = (
+        f"Fix the following exception:\n\nTitle: {payload.title}\n\n"
+        f"Stack trace / details:\n{payload.description}"
+    )
+    if payload.extra:
+        prompt += f"\n\nExtra context:\n{payload.extra}"
+
+    task = CodingTask(
+        source="exception",
+        source_id=payload.fingerprint,
+        repo_branch=payload.repo_branch,
+        prompt=prompt,
+    )
+    await task.insert(session)
+    await coding_tasks_pubsub.publish(CodingTaskMessage(task_id=task.id))
+
+    return TaskResponse(task_id=task.id, status="pending", message="Task queued")
+
+@router.post(
+    "/tasks",
+    dependencies=[Depends(raise_on_unauthenticated)]
+)
+async def create_manual_task(
+    payload: ManualTaskPayload,
+    session: SessionDep,
+) -> TaskResponse:
+
+    existing = await _dedup_check(session, payload.source_id)
+    if existing:
+        raise HTTPException(
+            status_code=409,
+            detail={"message": "Task already in progress", "task_id": str(existing.id)},
+        )
+
+    task = CodingTask(
+        source="manual",
+        source_id=payload.source_id,
+        repo_branch=payload.repo_branch,
+        prompt=payload.prompt,
+    )
+    await task.insert(session)
+    await coding_tasks_pubsub.publish(CodingTaskMessage(task_id=task.id))
+
+    return TaskResponse(task_id=task.id, status="pending", message="Task queued")
+
+
+@router.get(
+    "/tasks",
+    dependencies=[Depends(raise_on_unauthenticated)]
+)
+async def list_tasks(
+    session: SessionDep,
+) -> list[CodingTask]:
+    result = await session.exec(select(CodingTask).order_by(CodingTask.created_at.desc()).limit(50))  # type: ignore[union-attr]
+    return list(result.all())
+
+
+@router.get(
+    "/tasks/{task_id}",
+    dependencies=[Depends(raise_on_unauthenticated)],
+)
+async def get_task(
+    task_id: str,
+    session: SessionDep,
+) -> CodingTask:
+    import uuid as uuid_mod
+
+    task = await CodingTask.get(uuid_mod.UUID(task_id), session)
+    if task is None:
+        raise HTTPException(status_code=404, detail="Task not found")
+    return task

maur-0.1.0/src/maur/app.py

@@ -0,0 +1,40 @@
+import logging
+
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from sqlmodel import SQLModel
+
+from maur.api import router
+from maur.models import engine
+
+logger = logging.getLogger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    import logging
+    logging.basicConfig(level=logging.INFO)
+
+    logger.info("Creating db models")
+    async with engine().begin() as conn:
+        await conn.run_sync(SQLModel.metadata.create_all)
+    logger.info("Created all models")
+
+    yield
+
+
+app = FastAPI(
+    title="Maur Agent",
+    description="Autonomous code agent that processes coding tasks from exception, Slack, and Linear.",
+    version="0.1.0",
+    lifespan=lifespan,
+)
+
+
+@app.get("/health")
+def health() -> str:
+    return "ok"
+
+
+app.include_router(router)

maur-0.1.0/src/maur/components.py

@@ -0,0 +1,39 @@
+from takk.models import SecretClass, Subscriber
+from takk.secrets import NatsConfig
+from maur.worker import CodingTaskMessage, process_coding_task
+from maur.settings import GithubSettings, GitlabSettings, MaurSettings, db_setting_type, MaurLLMSettings
+from takk import FastAPIApp, Compute, PubSub, DockerBuild
+from takk.docker import ImageBuildArgs
+
+coding_tasks_pubsub = PubSub(
+    content_type=CodingTaskMessage,
+    subject="maur.tasks",
+)
+
+def maur_api(secrets: list[SecretClass] | None = None) -> FastAPIApp:
+    return FastAPIApp(
+        "maur.app",
+        health_check="/health",
+        secrets=secrets or [db_setting_type()],
+    )
+
+def maur_code_subscriber(
+    secrets: list[SecretClass] | None = None,
+    compute: Compute | None = None
+) -> Subscriber[CodingTaskMessage]:
+    return coding_tasks_pubsub.subscriber(
+        process_coding_task,
+        image=DockerBuild.default_uv_image(
+            image_name="coder", 
+            build_args={
+                ImageBuildArgs.uv_sync_args: "--locked --no-editable --active --all-groups",
+                ImageBuildArgs.apt_packages: "curl ca-certificates bash git libstdc++6 libgcc-s1 unzip jq grep",
+                ImageBuildArgs.install_opencode: "true"
+            }
+        ),
+        secrets=secrets or [db_setting_type(), MaurSettings, MaurLLMSettings, GithubSettings, GitlabSettings, NatsConfig],
+        compute=compute or Compute(
+            mb_memory_limit=1024 * 3
+        )
+    )
+