Contributing

Get started with UnaMentis and learn about our future plans for community contributions.

Current Status

📋 Not Accepting Code Contributions Yet

UnaMentis is currently in active early development. While we're excited about building a vibrant open source community in the future, we're not accepting pull requests or code contributions at this time.

What you can do now:

  • Explore the code: You're welcome to clone, fork, and experiment with the repository for your own learning and projects
  • Share ideas: We welcome suggestions and feedback via GitHub Discussions
  • Report issues: Found a bug? Let us know through GitHub Issues. Please note that during our MVP development, most issues may be closed immediately as we focus on our roadmap, but we'd rather receive concrete bug reports in case we're missing something critical. Our communication will improve significantly once we complete the initial MVP.
  • Stay tuned: We expect to open up contributions in the coming weeks or months as we refine our vision and establish clear contribution pathways

The sections below outline our future plans for community contributions. This represents where we're headed, not where we are today.

Quick Start

Get UnaMentis running on your machine in a few steps:

1

Clone the Repository

git clone https://github.com/unamentis/voicelearn-ios.git
cd voicelearn-ios
2

Open in Xcode

open UnaMentis.xcodeproj

Or use the command line build (see Building section below).

3

Configure API Keys

You'll need API keys for at least one provider in each category (STT, TTS, LLM). See the Settings page in the app to configure these.

For development without paid APIs, you can use the Apple on-device providers (Speech Framework for STT, Apple TTS) and a self-hosted LLM.

4

Run the App

Select iPhone 17 Pro simulator and press Run, or build from command line: 

xcodebuild -project UnaMentis.xcodeproj -scheme UnaMentis \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro' build

Requirements

Development Machine

  • macOS 14.0 (Sonoma) or later
  • Xcode 15.0 or later
  • Swift 6.0
  • Python 3.11+ (for server components)
  • Node.js 18+ (for web dashboard)

Target Device

  • iOS 17.0 or later
  • iPhone 15 Pro or newer (recommended)
  • iPad Pro M1 or newer (recommended)
  • Simulator works for development

Optional Tools

  • SwiftLint (code linting)
  • SwiftFormat (code formatting)
  • Homebrew (package management)
  • Docker (for self-hosted services)

API Keys (Optional)

  • OpenAI or Anthropic (LLM)
  • AssemblyAI or Deepgram (STT)
  • ElevenLabs or Deepgram (TTS)
  • OpenAI (Embeddings)

Building

iOS App

# Build for simulator
xcodebuild -project UnaMentis.xcodeproj -scheme UnaMentis \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro' build

# Build for device (requires signing)
xcodebuild -project UnaMentis.xcodeproj -scheme UnaMentis \
  -destination 'generic/platform=iOS' build

Server Components

# Create virtual environment
cd server
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run management server
python -m management.server

Web Dashboard

cd server/web
npm install
npm run dev

Testing

UnaMentis has over 119 automated tests with a "real over mock" philosophy. Only paid external APIs are mocked; all internal services use real implementations.

Running Tests

# Quick tests (unit tests only)
./scripts/test-quick.sh

# All tests (unit + integration)
./scripts/test-all.sh

# Run specific test class
xcodebuild test -project UnaMentis.xcodeproj -scheme UnaMentis \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
  -only-testing:UnaMentisTests/SessionManagerTests

# Health check (lint + quick tests)
./scripts/health-check.sh

Testing Philosophy

Real Over Mock

Only mock paid external APIs (LLM, STT, TTS, Embeddings). Use real implementations for all internal services.

Faithful Mocks

When mocking is necessary, simulate realistic delays, validate inputs, and reproduce all error conditions.

In-Memory Storage

Use PersistenceController(inMemory: true) for Core Data tests. Use temp directories for file operations.

Test Helpers

Use TestDataFactory for creating realistic test data. Use MockServices.swift for standardized mock implementations.

Code Style

UnaMentis follows strict coding standards documented in docs/IOS_STYLE_GUIDE.md.

Automated Tools

# Run linter
./scripts/lint.sh

# Run formatter
./scripts/format.sh

Key Requirements

Swift 6.0 Concurrency

  • All services must be actors
  • ViewModels use @MainActor
  • Types crossing actor boundaries must be Sendable

Accessibility

  • Labels on all interactive elements
  • Minimum 44x44pt touch targets
  • Support Dynamic Type scaling
  • Respect Reduce Motion preference

Localization

  • Use LocalizedStringKey for all user-facing text
  • iPad adaptive layouts using size class detection
  • Use NavigationStack (not NavigationView)

Writing Style

  • Never use em dashes or en dashes as sentence interrupters
  • Use commas for parenthetical phrases
  • Use periods to break up long sentences

Commit Convention

Follow Conventional Commits:

feat: add voice activity detection visualization
fix: resolve memory leak in audio buffer handling
docs: update API key configuration guide
test: add SessionManager interruption tests
refactor: extract audio processing to dedicated actor
perf: optimize TTS buffer scheduling
ci: add automated performance benchmarks
chore: update dependencies

Future: How to Contribute

The following represents our planned contribution workflow once we begin accepting code contributions.

1

Find or Create an Issue

Check existing issues or create a new one describing what you want to work on. Wait for maintainer feedback before starting significant work.

2

Fork and Branch

Fork the repository and create a feature branch from main. Use a descriptive branch name like feat/add-whisper-support.

3

Implement Changes

Follow the code style guide. Add tests for new functionality. Update documentation if needed.

4

Run Health Check

Before committing, run ./scripts/health-check.sh to ensure linting passes and tests succeed.

5

Submit Pull Request

Open a PR against main with a clear description of changes. Link to related issues. Be responsive to review feedback.

Future: Contribution Areas

These are the areas where we plan to welcome contributions in the future:

iOS Development

Help improve the iOS client with new features, bug fixes, and performance optimizations. Swift 6.0 and SwiftUI experience helpful.

Swift SwiftUI

Provider Integrations

Add support for new STT, TTS, or LLM providers. Improve existing integrations. All providers follow protocol-based design.

APIs Networking

Curriculum Content

Create UMLCF curriculum documents for various subjects. Help build importers for existing educational content.

Education Content

Server Development

Improve the Python management server or React web dashboard. Add new monitoring and analytics features.

Python React

Documentation

Improve documentation, write tutorials, create example curricula, or translate content to other languages.

Docs Technical Writing

Testing & QA

Add test coverage, improve test infrastructure, perform manual testing, or help with performance benchmarking.

Testing Quality

Accessibility

Ensure the app is accessible to all users. Test with VoiceOver, improve dynamic type support, and verify color contrast.

A11y Inclusion

On-Device ML

Help optimize on-device inference for STT (GLM-ASR), LLM (llama.cpp), or VAD models using CoreML.

ML CoreML

Community

Connect with the UnaMentis community:

📦

GitHub

Source code, issues, and pull requests
💬

Discussions

Ask questions and share ideas
🐛

Issues

Report bugs and request features

Maintainers

RA

Richard Amerman

Founder and Project Lead

CG

Cy Goerdt

Partner