Skip to content

Commit ccfc34d

Browse files
geethac2lgeethac2l
authored
Merge pull request #4 from cld2labs/dev/Audify
docs: update README benchmarks and rewrite CONTRIBUTING
2 parents ce34e6f + e91149c commit ccfc34d

3 files changed

Lines changed: 317 additions & 23 deletions

File tree

‎.github/workflows/code-scans.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ on:
77
description: 'Pull request number'
88
required: true
99
push:
10-
branches: [ main ]
10+
branches: [ main, dev/Audify ]
1111
pull_request:
1212
types: [opened, synchronize, reopened, ready_for_review]
1313

‎CONTRIBUTING.md‎

Lines changed: 313 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,313 @@
1-
# Contributing to Audify
2-
3-
Thank you for your interest in contributing to the
4-
**Audify** by Cloud2 Labs.
5-
6-
## Scope of Contributions
7-
Appropriate contributions include:
8-
- Documentation improvements
9-
- Bug fixes
10-
- Reference architecture enhancements
11-
- Educational clarity and examples
12-
13-
Major feature additions or architectural changes require prior discussion with
14-
the Cloud2 Labs maintainers.
15-
16-
## Contribution Guidelines
17-
- Follow existing coding and documentation standards
18-
- Avoid production-specific assumptions
19-
- Do not introduce sensitive, proprietary, or regulated data
20-
21-
By submitting a contribution, you agree that your work may be used, modified,
22-
and redistributed by Cloud2 Labs.
1+
# Contributing to Audify
2+
3+
Thanks for your interest in contributing to Audify.
4+
5+
Audify is an open-source AI application that turns documents into editable, two-speaker podcast-style scripts and downloadable audio using a FastAPI microservices backend and a React frontend. We welcome improvements across the codebase, documentation, bug reports, UX refinements, observability, and feature enhancements.
6+
7+
Before you start, read the relevant section below. It helps keep contributions focused, reviewable, and aligned with the current project setup.
8+
9+
---
10+
11+
## Quick Setup Checklist
12+
13+
Before you dive in, make sure you have these installed:
14+
15+
```bash
16+
# Check Python (3.11+ recommended)
17+
python --version
18+
19+
# Check Node.js (18+ recommended)
20+
node --version
21+
22+
# Check npm
23+
npm --version
24+
25+
# Check Docker
26+
docker --version
27+
docker compose version
28+
29+
# Check Git
30+
git --version
31+
```
32+
33+
New to contributing?
34+
35+
1. Open an issue or pick an existing one to work on.
36+
2. Sync your branch from `dev/Audify`.
37+
3. Follow the local setup guide below.
38+
4. Run the app locally and verify your change before opening a PR.
39+
40+
## Table of Contents
41+
42+
- [How do I...?](#how-do-i)
43+
- [Get help or ask a question?](#get-help-or-ask-a-question)
44+
- [Report a bug?](#report-a-bug)
45+
- [Suggest a new feature?](#suggest-a-new-feature)
46+
- [Set up Audify locally?](#set-up-audify-locally)
47+
- [Start contributing code?](#start-contributing-code)
48+
- [Improve the documentation?](#improve-the-documentation)
49+
- [Submit a pull request?](#submit-a-pull-request)
50+
- [Code guidelines](#code-guidelines)
51+
- [Pull request checklist](#pull-request-checklist)
52+
- [Branching model](#branching-model)
53+
- [Thank you](#thank-you)
54+
55+
---
56+
57+
## How do I...
58+
59+
### Get help or ask a question?
60+
61+
- Start with the main project docs in [`README.md`](./README.md), [`docs/PROJECT_ARCHITECTURE.md`](./docs/PROJECT_ARCHITECTURE.md), and the service-level READMEs under [`api/`](./api).
62+
- Review relevant config files such as [`simple_backend.py`](./simple_backend.py), [`api/llm-service/app/config.py`](./api/llm-service/app/config.py), and [`api/tts-service/app/config.py`](./api/tts-service/app/config.py).
63+
- If something is still unclear, open a GitHub issue with your question and the context you already checked.
64+
65+
### Report a bug?
66+
67+
1. Search existing issues first.
68+
2. If the bug is new, open a GitHub issue.
69+
3. Include your environment, what happened, what you expected, and exact steps to reproduce.
70+
4. Add screenshots, logs, request payloads, or response details if relevant.
71+
72+
### Suggest a new feature?
73+
74+
1. Open a GitHub issue describing the feature.
75+
2. Explain the problem, who it helps, and how it fits Audify.
76+
3. If the change is large, get alignment in the issue before writing code.
77+
78+
### Set up Audify locally?
79+
80+
#### Prerequisites
81+
82+
- Python 3.11+
83+
- Node.js 18+ and npm
84+
- Git
85+
- Docker with Docker Compose v2
86+
- One inference path for script generation:
87+
- Ollama or another OpenAI-compatible local inference endpoint, or
88+
- An OpenAI-compatible API endpoint for fallback or hosted inference
89+
- OpenAI API key for TTS generation
90+
91+
#### Option 1: Local Development
92+
93+
##### Step 1: Clone the repository
94+
95+
```bash
96+
git clone https://github.com/cld2labs/Audify.git
97+
cd Audify
98+
```
99+
100+
##### Step 2: Configure environment variables
101+
102+
Create the root `.env` file:
103+
104+
```bash
105+
cp .env.example .env
106+
```
107+
108+
If `.env.example` is not present in your branch, create `.env` manually using the values documented in [`README.md`](./README.md).
109+
110+
Create `api/llm-service/.env` with your inference settings. Example:
111+
112+
```env
113+
SERVICE_PORT=8002
114+
OPENAI_API_KEY=sk-...
115+
OPENAI_BASE_URL=
116+
INFERENCE_API_ENDPOINT=
117+
INFERENCE_API_TOKEN=
118+
INFERENCE_MODEL_NAME=gpt-4o-mini
119+
VLLM_BASE_URL=http://localhost:11434/v1
120+
VLLM_MODEL=Qwen/Qwen3-1.7B
121+
DEFAULT_MODEL=gpt-4o-mini
122+
DEFAULT_TONE=conversational
123+
DEFAULT_MAX_LENGTH=2000
124+
TEMPERATURE=0.7
125+
MAX_TOKENS=2048
126+
MAX_RETRIES=3
127+
```
128+
129+
Create `api/tts-service/.env` with your TTS settings. Example:
130+
131+
```env
132+
SERVICE_PORT=8003
133+
OPENAI_API_KEY=sk-...
134+
TTS_MODEL=tts-1-hd
135+
DEFAULT_HOST_VOICE=alloy
136+
DEFAULT_GUEST_VOICE=nova
137+
OUTPUT_DIR=static/audio
138+
AUDIO_FORMAT=mp3
139+
AUDIO_BITRATE=192k
140+
SILENCE_DURATION_MS=500
141+
MAX_CONCURRENT_REQUESTS=5
142+
MAX_SCRIPT_LENGTH=100
143+
```
144+
145+
##### Step 3: Install backend dependencies
146+
147+
```bash
148+
python -m venv .venv
149+
source .venv/bin/activate # Windows: .venv\Scripts\activate
150+
pip install -r requirements.txt
151+
pip install -r api/pdf-service/requirements.txt
152+
pip install -r api/llm-service/requirements.txt
153+
pip install -r api/tts-service/requirements.txt
154+
```
155+
156+
##### Step 4: Install frontend dependencies
157+
158+
```bash
159+
cd ui
160+
npm install
161+
cd ..
162+
```
163+
164+
##### Step 5: Start the backend services
165+
166+
Open separate terminals and start:
167+
168+
```bash
169+
# Terminal 1: gateway
170+
source .venv/bin/activate
171+
python simple_backend.py
172+
```
173+
174+
```bash
175+
# Terminal 2: PDF service
176+
source .venv/bin/activate
177+
cd api/pdf-service
178+
uvicorn app.main:app --reload --host 0.0.0.0 --port 8001
179+
```
180+
181+
```bash
182+
# Terminal 3: LLM service
183+
source .venv/bin/activate
184+
cd api/llm-service
185+
uvicorn app.main:app --reload --host 0.0.0.0 --port 8002
186+
```
187+
188+
```bash
189+
# Terminal 4: TTS service
190+
source .venv/bin/activate
191+
cd api/tts-service
192+
uvicorn app.main:app --reload --host 0.0.0.0 --port 8003
193+
```
194+
195+
##### Step 6: Start the frontend
196+
197+
Open another terminal:
198+
199+
```bash
200+
cd ui
201+
npm run dev
202+
```
203+
204+
##### Step 7: Access the application
205+
206+
- Frontend: `http://localhost:5173` in local Vite development, or `http://localhost:3000` when using Docker
207+
- Backend gateway health check: `http://localhost:8000/health`
208+
- PDF service docs: `http://localhost:8001/docs`
209+
- LLM service docs: `http://localhost:8002/docs`
210+
- TTS service docs: `http://localhost:8003/docs`
211+
212+
#### Option 2: Docker
213+
214+
From the repository root:
215+
216+
```bash
217+
# Create and configure the required env files first
218+
docker compose up --build
219+
```
220+
221+
This starts:
222+
223+
- Frontend on `http://localhost:3000`
224+
- Backend gateway on `http://localhost:8000`
225+
- PDF service on `http://localhost:8001`
226+
- LLM service on `http://localhost:8002`
227+
- TTS service on `http://localhost:8003`
228+
229+
#### Common Troubleshooting
230+
231+
- If ports `3000`, `8000`, `8001`, `8002`, or `8003` are already in use, stop the conflicting process before starting Audify.
232+
- If script generation fails, confirm the LLM service `.env` points to a reachable model endpoint.
233+
- If you use Ollama with Docker, make sure Ollama is running on the host and reachable from the container.
234+
- If audio generation fails, verify `OPENAI_API_KEY` is set in `api/tts-service/.env`.
235+
- If Docker fails to build, rebuild with `docker compose up --build`.
236+
- If Python packages fail to install, confirm you are using a supported Python version.
237+
238+
### Start contributing code?
239+
240+
1. Open or choose an issue.
241+
2. Create a feature branch from `dev/Audify`.
242+
3. Keep the change focused on a single problem.
243+
4. Run the app locally and verify the affected workflow.
244+
5. Update docs when behavior, setup, configuration, or architecture changes.
245+
6. Open a pull request from your feature branch into `dev/Audify`.
246+
247+
### Improve the documentation?
248+
249+
Documentation updates are welcome. Relevant files currently live in:
250+
251+
- [`README.md`](./README.md)
252+
- [`docs/`](./docs/)
253+
- [`api/pdf-service/README.md`](./api/pdf-service/README.md)
254+
- [`api/llm-service/README.md`](./api/llm-service/README.md)
255+
- [`api/tts-service/README.md`](./api/tts-service/README.md)
256+
- [`benchmarks/README.md`](./benchmarks/README.md)
257+
258+
### Submit a pull request?
259+
260+
Follow the checklist below before opening your PR. Your pull request should:
261+
262+
- Stay focused on one issue or topic.
263+
- Explain what changed and why.
264+
- Include manual verification steps.
265+
- Include screenshots or short recordings for UI changes.
266+
- Reference the related GitHub issue when applicable.
267+
268+
Note: pull requests should target the `dev/Audify` branch unless maintainers ask otherwise.
269+
270+
---
271+
272+
## Code guidelines
273+
274+
- Follow the existing project structure and patterns before introducing new abstractions.
275+
- Keep frontend changes consistent with the React + Vite + Tailwind setup already in use under [`ui/`](./ui/).
276+
- Keep backend changes consistent with the FastAPI microservice structure under [`api/`](./api/) and the gateway in [`simple_backend.py`](./simple_backend.py).
277+
- Avoid unrelated refactors in the same pull request.
278+
- Do not commit secrets, API keys, local `.env` files, generated audio, or benchmark artifacts that do not belong in version control.
279+
- Prefer clear, small commits and descriptive pull request summaries.
280+
- Update documentation when contributor setup, behavior, environment variables, or service logic changes.
281+
- If you change API contracts, verify both the service endpoint and the frontend consumer still match.
282+
283+
---
284+
285+
## Pull request checklist
286+
287+
Before submitting your pull request, confirm the following:
288+
289+
- You tested the affected flow locally.
290+
- The application still starts successfully in the environment you changed.
291+
- You removed debug code, stray logs, and commented-out experiments.
292+
- You documented any new setup steps, environment variables, or behavior changes.
293+
- You kept the pull request scoped to one issue or topic.
294+
- You added screenshots for UI changes when relevant.
295+
- You did not commit secrets, API keys, sample private documents, or generated media outputs by mistake.
296+
- You are opening the pull request against `dev/Audify`.
297+
298+
If one or more of these are missing, the pull request may be sent back for changes before review.
299+
300+
---
301+
302+
## Branching model
303+
304+
- Base new work from `dev/Audify`.
305+
- Open pull requests against `dev/Audify`.
306+
- Use descriptive branch names such as `fix/script-generation-timeout` or `docs/update-contributing-guide`.
307+
- Rebase or merge the latest `dev/Audify` before opening your PR if your branch has drifted.
308+
309+
---
310+
311+
## Thank you
312+
313+
Thanks for contributing to Audify. Whether you are fixing a bug, improving the docs, refining the UI, strengthening the service architecture, or making the generation workflow more reliable, your work helps make the project more useful and easier to maintain.

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -395,14 +395,17 @@ The table below compares inference performance across different providers, deplo
395395
| Provider | Model | Deployment | Context Window | Avg Input Tokens | Avg Output Tokens | Avg Tokens / Request | P50 Latency (ms) | P95 Latency (ms) | Throughput (req/s) | Hardware |
396396
|----------|-------|------------|----------------|------------------|-------------------|----------------------|------------------|------------------|--------------------|----------|
397397
| vLLM | `Qwen/Qwen3:1.7b` | Local | 4,096 | 1,183 | 1,308 | 2,492 | 58,855 | 59,773 | 0.0162 | Apple Silicon Metal (Macbook Pro M4) |
398+
| OPEA EI / SLM | `Qwen/Qwen3:1.7b` | Local | 8.1K | 1,075 | 350 | 1,425 | 10,446 | 23,445 | 0.0853 | Xeon CPU (CPU only) |
398399
| OpenAI (Cloud) | `gpt-4o-mini` | API (Cloud) | 128K | 1,625 | 680 | 2,330 | 19,848 | 20,733 | 0.0276 | Cloud GPUs |
399400

400401
> **Notes:**
401402
>
402403
> - Context Window for vLLM (4,096) reflects the `LLM_MAX_TOKENS` / `--max-model-len` used during benchmarking, not the model's native maximum context. vLLM shares its configured context between input and output tokens.
404+
> - EI is configured with an 8,192-token context window for this benchmark run.
403405
> - All benchmarks use the same Audify script-generation prompt and identical inputs across 3 runs.
404406
> - Token counts may vary slightly per run due to non-deterministic model output.
405407
> - vLLM on Apple Silicon requires [vllm-metal](https://github.com/vllm-project/vllm-metal); the standard `pip install vllm` package does not provide macOS Metal support.
408+
> - [Intel OPEA EI](https://github.com/opea-project/Enterprise-Inference) runs on Intel Xeon CPUs without GPU acceleration.
406409
407410
---
408411

0 commit comments

Comments
 (0)