miniflow by smallest.ai

Author: malikaa-27

.editorconfig

@@ -0,0 +1,14 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+trim_trailing_whitespace = true
+
+[*.{swift,py,ts,tsx,js,jsx,md,yml,yaml}]
+indent_style = space
+indent_size = 4
+
+[*.md]
+trim_trailing_whitespace = false

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,20 @@
+---
+name: Bug report
+description: Report a bug
+labels: [bug]
+---
+
+## Description
+
+## Steps to reproduce
+
+## Expected behavior
+
+## Actual behavior
+
+## Environment
+- macOS version:
+- MiniFlow version:
+
+## Logs
+Paste relevant lines from `~/miniflow/miniflow.log`.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security issue
+    url: mailto:developer@smallest.ai
+    about: Report a security vulnerability

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,13 @@
+---
+name: Feature request
+description: Suggest an idea
+labels: [enhancement]
+---
+
+## Problem
+
+## Proposed solution
+
+## Alternatives considered
+
+## Additional context

.github/workflows/build.yml

@@ -0,0 +1,48 @@
+name: Build MiniFlow DMG
+
+on:
+  push:
+    branches: [main, ui, development, ai]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: macos-15
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Get version
+        id: version
+        run: |
+          VERSION=$(grep -m1 'MARKETING_VERSION' MiniflowApp/MiniflowApp.xcodeproj/project.pbxproj \
+            | sed 's/.*= *//;s/;//;s/ *//')
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Create venv & install dependencies
+        run: |
+          cd miniflow-engine
+          python3 -m venv venv
+          source venv/bin/activate
+          pip install --upgrade pip
+          pip install -r requirements.txt
+
+      - name: Build (backend + Swift app + DMG)
+        run: |
+          chmod +x build_all.sh build_backend.sh build_dmg.sh
+          ./build_all.sh
+        env:
+          CONFIG: Release
+
+      - name: Upload DMG
+        uses: actions/upload-artifact@v4
+        with:
+          name: MiniFlow-${{ steps.version.outputs.version }}
+          path: build/MiniFlow-${{ steps.version.outputs.version }}.dmg
+          retention-days: 30

.github/workflows/release.yml

@@ -0,0 +1,53 @@
+name: Build DMG
+
+on:
+  push:
+    branches:
+      - main
+      - audioTransmission
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version override (e.g. 0.2.1). Leave blank to read from project.'
+        required: false
+        default: ''
+
+jobs:
+  build:
+    runs-on: macos-14
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Get version
+        id: version
+        run: |
+          if [ -n "${{ github.event.inputs.version }}" ]; then
+            VERSION="${{ github.event.inputs.version }}"
+          else
+            VERSION=$(grep -m1 'MARKETING_VERSION' MiniflowApp/MiniflowApp.xcodeproj/project.pbxproj \
+              | sed 's/.*= *//;s/;//;s/ *//')
+          fi
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Create venv & install dependencies
+        run: |
+          python3 -m venv miniflow-engine/venv
+          miniflow-engine/venv/bin/pip install --upgrade pip
+          miniflow-engine/venv/bin/pip install -r miniflow-engine/requirements.txt
+
+      - name: Build (backend + Swift app + DMG)
+        run: VERSION=${{ steps.version.outputs.version }} bash build_all.sh
+
+      - name: Upload DMG artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: MiniFlow-${{ steps.version.outputs.version }}
+          path: build/MiniFlow-${{ steps.version.outputs.version }}.dmg
+          retention-days: 14

.gitignore

@@ -0,0 +1,48 @@
+# Build outputs
+build/
+miniflow-engine/dist/
+miniflow-engine/build/
+miniflow-engine/__pycache__/
+miniflow-engine/*.spec
+**/__pycache__/
+**/*.pyc
+
+# Xcode
+*.xcuserdata/
+xcuserdata/
+DerivedData/
+*.xcbuilddata
+*.xcresult
+*.dSYM
+
+# Node / Vite
+node_modules/
+dist/
+
+# macOS
+.DS_Store
+**/.DS_Store
+
+# Secrets / config (never commit API keys)
+miniflow/
+oauth_clients.json
+miniflow_keys.json
+*.env
+.env*
+
+# Python venvs
+miniflow-engine/.venv/
+miniflow-engine/venv/
+
+# Claude internal docs
+.claude/
+
+# Vercel deployment config
+.vercel/
+
+# IDE config
+.vscode/
+
+# Runtime files
+miniflow.log
+history.json

CODE_OF_CONDUCT.md

@@ -0,0 +1,28 @@
+# Code of Conduct
+
+We follow the Contributor Covenant.
+
+## Our Pledge
+
+We pledge to make participation in our community a harassment-free experience for everyone.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Accepting constructive criticism
+
+Examples of unacceptable behavior include:
+
+- Harassment, trolling, or personal attacks
+- Publishing others' private information
+
+## Enforcement
+
+Instances of abusive behavior may be reported to developer@smallest.ai.
+
+## Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 2.1.

CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing
+
+Thanks for helping improve MiniFlow.
+
+## Quick start
+
+1. Fork the repo and create a feature branch.
+2. Make your changes.
+3. Run existing scripts/tests if relevant.
+4. Open a PR with a clear description.
+
+## Development notes
+
+- Swift app lives in `MiniflowApp/`.
+- Python engine lives in `miniflow-engine/`.
+- Build the DMG with `./build_all.sh`.
+
+## Code style
+
+- Keep changes focused and minimal.
+- Prefer small, reviewable commits.
+
+## Reporting issues
+
+Please include:
+- macOS version
+- Steps to reproduce
+- Expected vs actual behavior
+- Logs from `~/miniflow/miniflow.log`

ENGINEERING.md

@@ -0,0 +1,64 @@
+# MiniFlow Engineering (Swift + Smallest)
+
+This repository is intentionally structured around a single runtime path:
+
+- `MiniflowApp/` - native macOS app (Swift/SwiftUI)
+- `miniflow-engine/` - local Python engine (FastAPI)
+- `miniflow-auth/` - OAuth proxy (Vercel, optional for integrations)
+
+Legacy web/Tauri artifacts have been removed from the root to avoid split build paths.
+
+## System Architecture
+
+```text
+MiniflowApp (Swift)  <->  miniflow-engine (FastAPI on localhost:8765)
+                                  |
+                                  +-> Smallest AI Waves (speech-to-text)
+                                  +-> OpenAI (agent/tool orchestration)
+                                  +-> OAuth-backed connectors (Slack, GitHub, etc.)
+```
+
+## Speech and Command Flow
+
+1. Swift captures microphone audio.
+2. Swift posts base64 PCM chunks to engine commands (`start_listening`, `send_audio_chunk`, `stop_listening`).
+3. Engine streams audio to Smallest AI Waves over WebSocket.
+4. Engine emits transcript events over `ws://127.0.0.1:8765/ws`.
+5. Swift receives final transcript and invokes `execute_command`.
+6. Engine runs local tools and connector tools, then emits action results.
+
+## API Key Contract
+
+The engine key contract is:
+
+- `openai`
+- `smallest`
+
+`has_api_keys` returns:
+
+```json
+{
+  "openai": "string|null",
+  "smallest": "string|null"
+}
+```
+
+## Build and Packaging
+
+Primary build path:
+
+1. `./build_backend.sh` - bundles Python engine
+2. `./build_all.sh` - builds Swift app, embeds engine, creates DMG
+
+DMG-only packaging (for an already built app):
+
+- `APP_PATH=build/MiniFlow.app ./build_dmg.sh`
+
+## Source of Truth
+
+If docs conflict with code, treat these as canonical:
+
+- Runtime and UI behavior: `MiniflowApp/`
+- Engine API/events: `miniflow-engine/main.py`
+- STT provider behavior: `miniflow-engine/audio.py`
+- API key storage contract: `miniflow-engine/config.py`