# Project export: Arka This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small. ## Project metadata - Hackathon: OpenAI Build Week - Tagline: Arka upgrades your terminal: plain English in, 70+ local skills out. Offline routing first with 24 provider llm fallback orchestration, AI when you need it. - Devpost: https://devpost.com/software/arka-291yab - GitHub: https://github.com/Sumit884-byte/arka - Demo: https://pypi.org/project/arka-agent/ - Video: https://www.youtube.com/embed/UmuQ3tqahD8?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent - Team: 2 GitHub contributor(s) — Sumit Mishra (72 commits), mintlify[bot] (2 commits) ## Devpost submission (written by the team) ### Overview GitHub · PyPI: arka-agent · Docs ### Inspiration We wanted a local-first AI agent that actually does things in the terminal — not another chat window that hallucinates shell commands. Most assistants treat the repo as an afterthought: they guess test commands, miss project-specific scripts, and burn tokens on routing that should be deterministic. Arka started from a simple idea: route plain English to real, local skills with symbolic rules first and LLMs only when needed. Over the week of July 14–20, 2026, that grew into something we could ship: a PyPI package (arka-agent 0.1.0), a Mintlify docs site with real install paths, an interactive coding TUI for plan → execute → test loops, MCP tools for Cursor, and a hosted remote UI on Railway. We built Arka the way we wanted to use it — pair-programming with Codex in Cursor, letting the agent fix CI, write docs, discover scripts, and iterate on routing while we focused on architecture and product decisions. ### What it does Arka is your terminal, upgraded. It routes natural language to 70+ local skills using 120+ symbolic rules before any LLM is called. Core routing & dev workflows Deterministic NL routing for dev tasks: route audit, CI checks, code review, natural-language PR creation Symbolic URL repair and exact-url routing Screenshot-to-design project routing Language-agnostic lint project command Recurring self-improve scheduling Coding TUI — the centerpiece /plan — LLM-generated plans in plan-only mode, with local fallback /run — execute goals with resilient git handling and honest pytest reporting /test — strict read-only test mode vs. flexible /run tests with optional --fix /ci and /review shortcuts, enriched /status, auto-execute on plan approval Greenfield project support outside the Arka repo Agentic script discovery — script_discovery.py finds verification scripts under scripts/ via heuristics (stem patterns, docstrings, argparse), not hardcoded names; wired into repo_health and the coding TUI MCP & IDE integration arka mcp serve documented and configured for Cursor arka mcp self-tools — lists native MCP tools for self-discovery Heartbeat, jsonkit, and other MCP-exposed tools wired into NL routing Remote UI & hosting React-based remote coding demo with Dockerfile and Railway deploy config Profile tests for coding server behavior Creative & media skills 3D generation with free backends (Hugging Face, Meshy, procedural fallback) Slide composition with pitch/executive themes Deterministic 3D space scaffold with auto-install of trusted dependencies Docs, PyPI, and distribution Published arka-agent 0.1.0 on PyPI — pipx install "arka-agent[chat]" and go Mintlify docs at arka-agent.mintlify.site: five top-level tabs, sidebar icons on every page, install guides for macOS/Linux/Windows New guides: "How to code with Arka," hosted mode, MCP, loop engineering, and more ### How we built it We worked in a tight loop: Codex in Cursor + Arka itself, shipping ~40 commits in six days. Architecture Python 3.11+ monorepo with optional extras (chat, observability, 3d, video, etc.) in pyproject.toml fish shell as the NL router front-end; Python CLI (arka) as the skill dispatcher Symbolic routing layer (src/arka/routing/symbolic.py) handles most intents with zero tokens; LLM failover across 24 providers when needed Skill plugins via skill.json — no fork required to extend Key implementation decisions How Codex helped Codex was our pair-programming partner throughout: Routing fixes — caught coding-tui being misrouted to web_answer instead of the TUI skill CI triage — aligned MCP tests when Spotify tool was disabled; cleared ruff errors Test reliability — made /run tests call pytest honestly; handled skipped commands and bad JSON from the goal agent Script discovery — helped design the heuristic classifier and write tests (test_script_discovery.py) Docs — drafted Mintlify guides, tightened prose, added install paths and platform tables to README PyPI readiness — updated README with pipx install, GitHub fallback, and contributor clone paths We also dogfooded Arka: the self-improve loop re-indexed the repo, and we used the coding TUI's /plan → approve → auto-execute flow for feature work. ### Challenges we ran into Routing is harder than it looks Early in the week, typing "coding tui" in fish landed on web_answer instead of launching the TUI. We added explicit routes, tests for NL parsing, and a route-audit dev tool to catch mismatches. /run tests lied (briefly) The goal agent would report success without actually running pytest. We split concerns: /test always runs repo-detected tests directly; /run tests goes through the readonly goal agent unless --fix is passed. Codex helped trace the dishonest reporting path and write the fix. CI kept breaking on small changes Disabling the Spotify MCP tool broke tests that still expected it. Ruff flagged unused imports in CI-only paths. Each fix was small but blocked merges — Codex was useful for running the exact failing test, patching the assertion, and clearing lint in one pass. Greenfield vs. in-repo assumptions The coding TUI assumed it was always running inside the Arka repo. Greenfield projects outside Arka's scope crashed or skipped useful commands. We added scope detection and safer defaults. Docs sprawl Mintlify had orphaned pages and no consistent nav. Restructuring into five tabs and adding icons to every page took a dedicated push — tedious but necessary for a public launch. Remote UI + Railway Shipping a hosted demo meant Dockerfile, env examples (.env.railway.example), profile-specific server behavior, and profile tests. Getting the coding profile to behave correctly over HTTP was non-trivial. ### Accomplishments we're proud of Shipped arka-agent 0.1.0 on PyPI — anyone can pipx install "arka-agent[chat]" and run arka setup without cloning the repo Coding TUI end-to-end loop — /plan → approve → auto-execute → /test with honest pytest output and optional auto-fix script_discovery.py — no hardcoded script manifest; heuristics find test/verify/smoke scripts in any repo Mintlify docs site — five tabs, icons everywhere, platform-specific install guides MCP in Cursor — documented config, self-tools discovery, NL routes in sync with terminal routing Remote coding UI on Railway — shareable demo without local setup 40+ commits in six days — routing, TUI, docs, MCP, 3D, slides, observability, CI — with Codex as a genuine force multiplier Security by default — prompt-injection checks, risky-action prompts, and hard blocks on destructive shell patterns ### What we learned Deterministic routing first, LLM second. Every symbolic rule we added cut latency and made behavior predictable. The LLM is for planning and edge cases, not "what command should I run?" Split read-only from agent-assisted paths. Users need a trustworthy /test before they'll trust auto-fix. Dogfooding catches real bugs. Using the coding TUI on Arka itself surfaced greenfield assumptions and routing drift unit tests missed. AI pair programming works when scopes are clear. Codex excelled at CI fixes, test writing, docs prose, and routing bugs. We owned architecture (script discovery heuristics, MCP tool surface, TUI session model). Docs are part of the product. Restructuring Mintlify felt like overhead until someone installed from PyPI using only the docs site. Publish early. Getting 0.1.0 on PyPI forced us to nail install paths, platform tables, and arka doctor. ### What's next Near term Polish the remote UI — session persistence, file tree browsing, tighter integration with the local coding TUI Expand script discovery — support package.json scripts, Makefile targets, and monorepo layouts More MCP tools in NL routing — full self-tools surface reachable from fish without memorizing names Windows portable mode — document and test the Python-only fallback path more thoroughly Medium term Plugin marketplace — third-party skill.json plugins installable via arka skill install Team / hosted mode — build on Railway deploy and backend client work for shared agent sessions Observability defaults — one-command arka observability setup that instruments the agent itself Voice + multimodal — extend screenshot-to-design and 3D scaffolds to voice-driven coding sessions Long term Self-improve on autopilot — open PRs for routing gaps Arka finds in its own telemetry Cross-agent interoperability — Arka as the local execution layer for Cursor, Codex, Claude Code, and other IDE agents via MCP, with shared session memory ## README (from the GitHub repository) # Arka **Your terminal, upgraded.** Route plain English to **70+ local skills** — deterministic offline routing, voice, 24-provider LLM failover, and security gates on by default. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/) [![PyPI](https://img.shields.io/pypi/v/arka-agent.svg)](https://pypi.org/project/arka-agent/) [![Downloads](https://static.pepy.tech/badge/arka-agent)](https://pepy.tech/projects/arka-agent) [![Downloads/month](https://img.shields.io/pypi/dm/arka-agent.svg)](https://pypistats.org/packages/arka-agent) [![GitHub](https://img.shields.io/github/stars/Sumit884-byte/arka?style=social)](https://github.com/Sumit884-byte/arka) [![Docs](https://img.shields.io/badge/docs-Mintlify-6366F1)](https://arka-agent.mintlify.site) [![GHCR](https://img.shields.io/badge/ghcr-arka-blue)](https://github.com/Sumit884-byte/arka/pkgs/container/arka) **Documentation:** [arka-agent.mintlify.site](https://arka-agent.mintlify.site) · **Repository:** [github.com/Sumit884-byte/arka](https://github.com/Sumit884-byte/arka) · Local landing preview: [`landing/`](landing/) (`python3 -m http.server` from that folder) ### PyPI downloads | Window | Downloads (no mirrors) | |--------|------------------------:| | Last 7 days | 23 | | Last 30 days | 63 | | Tracked since launch (2026-07-20) | 447 | | With mirrors (same window) | 1,585 | Live charts: [pypistats.org/packages/arka-agent](https://pypistats.org/packages/arka-agent) · [pepy.tech/projects/arka-agent](https://pepy.tech/projects/arka-agent) · snapshot 2026-08-30 ## Why Arka? - **Deterministic routing:** 120+ symbolic rules handle most requests with zero LLM tokens before any model is called. - **Extensible:** Add third-party skills via `skill.json` plugins — no fork required. - **Secure by default:** Prompt-injection checks, risky-action prompts, and hard blocks on destructive shell patterns. - **Local-first:** Skills run on your machine; LLM calls failover across Gemini, Groq, Ollama, and 20+ other providers. If Arka looks useful, **star the upstream repo** — it helps others discover the project and signals that it's worth a look: ```bash gh repo star Sumit884-byte/arka ``` Or open [github.com/Sumit884-byte/arka](https://github.com/Sumit884-byte/arka) and click **Star**. ## Architecture Arka is built as a layered system. Requests flow through deterministic symbolic routing first (zero LLM tokens), fall back to a multi-provider LLM chain only when needed, and dispatch to a pluggable skill dispatcher. All layers — MCP server, remote API server, memory, telemetry, and cloud deployment — are independently composable. ```mermaid flowchart TD CLI["🖥️ CLI / Natural Language Input\n`arka ...` or `arka ask '...'`"] subgraph Router["Routing Layer (zero-token-first)"] SR["⚡ Symbolic Router\n120+ deterministic rules"] LLM["🤖 LLM Failover Chain\nGemini → Groq → Ollama\n→ OpenRouter → 20+ providers"] SR -->|"no match"| LLM end subgraph Dispatch["Skill Dispatcher"] SD["🎯 Skill Dispatcher\nHosted-mode guard · Security gate\nPrompt-injection check"] end subgraph Skills["70+ Skills"] direction TB CODE["💻 Code & Repo\ncode · repo_health · repo_map\nreview · ci · pr_check · security"] DATA["📊 Data & Research\nask · search · pdf_rag\nstocks · data_ask · kaggle"] MEDIA["🎵 Media & Voice\nvoice · youtube · spotify\ncompose_video · tts"] INFRA["☁️ Infra & Deploy\ndeploy · cloud · railway\ndocker · render · vercel"] MEM["🧠 Memory\nmemory · recall · supermemory\ncontext · session"] end subgraph Interfaces["Interfaces"] MCP["🔌 MCP Server\nstdio / SSE\nCursor · Claude · Copilot"] REMOTE["🌐 Remote HTTP API\nGET /v1/health\nPOST /v1/agent\nMobile UI :8765"] TLM["📡 Telemetry\nOpenTelemetry · SigNoz"] end subgraph LLMs["LLM Providers"] G["Gemini"] GQ["Groq"] OL["Ollama (local)"] OR["OpenRouter\n+ 20 providers"] end CLI --> Router SR -->|"matched rule"| SD LLM --> G & GQ & OL & OR LLM --> SD SD --> CODE & DATA & MEDIA & INFRA & MEM SD --> MCP SD --> REMOTE SD --> TLM style CLI fill:#1e293b,color:#f8fafc,stroke:#f97316 style SR fill:#0f172a,color:#fb923c,stroke:#f97316 style LLM fill:#0f172a,color:#a78bfa,stroke:#7c3aed style SD fill:#0f172a,color:#34d399,stroke:#059669 style MCP fill:#0f172a,color:#60a5fa,stroke:#2563eb style REMOTE fill:#0f172a,color:#60a5fa,stroke:#2563eb style TLM fill:#0f172a,color:#94a3b8,stroke:#475569 style CODE fill:#0f172a,color:#f8fafc,stroke:#334155 style DATA fill:#0f172a,color:#f8fafc,stroke:#334155 style MEDIA fill:#0f172a,color:#f8fafc,stroke:#334155 style INFRA fill:#0f172a,color:#f8fafc,stroke:#334155 style MEM fill:#0f172a,color:#f8fafc,stroke:#334155 style G fill:#1a2744,color:#93c5fd,stroke:#1d4ed8 style GQ fill:#1a2744,color:#93c5fd,stroke:#1d4ed8 style OL fill:#1a2744,color:#93c5fd,stroke:#1d4ed8 style OR fill:#1a2744,color:#93c5fd,stroke:#1d4ed8 ``` **Key design properties:** - **Zero-token-first** — Symbolic routing resolves most requests without any LLM call. - **Hosted-mode safety** — Skill dispatcher blocks desktop/GUI/audio skills automatically on cloud/headless Linux (`ARKA_HOSTED_MODE=1`). - **Multi-platform deploy** — `arka deploy --all` deploys to Cloud VM, Railway, Vercel, Netlify, Render in one command. - **MCP + Remote API** — Arka exposes all skills as MCP tools (stdio/SSE) and a REST HTTP API on port 8765. ## Privacy Arka is designed so **you stay in control of your data**: - **Runs on your machine** — Skills execute locally. There is no hosted Arka account and no shared demo instance; your terminal, files, and config stay on your system. - **Local-first routing** — 120+ symbolic rules handle many requests with **zero LLM tokens**, so common tasks never leave your machine. - **You choose where prompts go** — LLM calls use only the providers you configure (Gemini, Groq, Ollama, etc.). For sensitive work, force a local-only boundary: ```bash arka run-only-local-llm "summarize this repo" arka hybrid config local-only ``` With `local-only`, hosted providers are not used as fallbacks. - **Secrets stay local** — API keys and `.env` live under your user config directory (`~/.config/arka/` on Linux, `~/Library/Application Support/arka/` on macOS). `arka integration setup` never prints secret values. - **Memory stays local by default** — Long-term memory uses a local cache unless you add a Supermemory key (`MEMORY=auto` falls back to local). Set `MEMORY=local` to keep recall entirely on disk. - **Web content is sanitized** — Arka strips suspicious injection patterns from search results and scraped pages before they reach the model (`SECURITY_SANITIZE=1` by default). - **Risky actions need confirmation** — Installs, deletes, downloads, and automation prompt `[y/N]` unless you explicitly auto-confirm (`SECURITY_ACTIONS=1` by default). - **Telemetry defaults to SigNoz** — OpenTelemetry traces, metrics, and logs export to `http://127.0.0.1:4318` by default. Set `OTEL_SDK_DISABLED=true` or `OTEL_TRACES_ENABLED=0` to opt out. Details: [Security model](https://arka-agent.mintlify.site/concepts/security) · [Memory](https://arka-agent.mintlify.site/guides/memory) · [Hybrid local/hosted routing](https://arka-agent.mintlify.site/guides/integrations#local-and-hosted-models-together) ## Supported platforms | Platform | Support | | --- | --- | | **macOS** | Full support — recommended for daily use | | **Linux** | Full support | | **Windows** | Python CLI and `arka` subcommands work; the full 70+ skill router needs [fish shell](https://fishshell.com) (`scoop install fish` or `winget install fishshell`). Without fish, Arka runs in **porta [README truncated for size] ## Detected evidence (automated analysis) Indexed codebase: 1523 recognized source files, 9505 KB. - CSS (language) — detected in the code - FastAPI (technology) — detected in the code - HTML (language) — detected in the code - Hugging Face (technology) — detected in the code - JavaScript (language) — detected in the code - OpenAI (technology) — detected in the code - Python (language) — detected in the code - PyTorch (technology) — detected in the code - React (technology) — detected in the code - Rust (language) — detected in the code - Streamlit (technology) — detected in the code - TypeScript (language) — detected in the code - Docker (technology) — claimed on Devpost, not found in the code - Google Gemini (technology) — claimed on Devpost, not found in the code - Ollama (technology) — claimed on Devpost, not found in the code - AI coding agent: Codex — evidence: config files committed to the repository ## Codebase structure (from repository index) ### Files (120 of 2224) ``` .arka-index .coderabbit.yaml .env.example .env.railway.example .githooks/prepare-commit-msg .github/workflows/ci.yml .github/workflows/pages.yml .github/workflows/publish.yml .gitignore arka-scene/index.html arka-scenes/animated-robot-gallery-fixed/index.html arka-scenes/animated-robot-gallery/index.html bin/_shim_path.py bin/arka_agent_hub.py bin/arka_agent.py bin/arka_ai_video.py bin/arka_aie.py bin/arka_alert.py bin/arka_ascii_art.py bin/arka_assemblyai_stt.py bin/arka_astronomy.py bin/arka_batch_summarize.py bin/arka_benchmark.py bin/arka_bi_dashboard.py bin/arka_bookmarks.py bin/arka_chart_from_pdf.py bin/arka_chart.py bin/arka_chat.py bin/arka_clipboard_history.py bin/arka_coderabbit.py bin/arka_competition_funding.py bin/arka_competitions.py bin/arka_compose_3d.py bin/arka_compose_slides.py bin/arka_compose_story.py bin/arka_compose_video.py bin/arka_compute.py bin/arka_config.py bin/arka_convert_media.py bin/arka_council.py bin/arka_create_video.py bin/arka_currency.py bin/arka_daily_brief.py bin/arka_daily_reading.py bin/arka_data_ask.py bin/arka_day_research.py bin/arka_describe_image.py bin/arka_describe_video.py bin/arka_dev_tools.py bin/arka_devto_post.py bin/arka_disk.py bin/arka_docker_status.py bin/arka_drawing.py bin/arka_dub_video.py bin/arka_edit_video.py bin/arka_elon.py bin/arka_email_contacts.py bin/arka_fact_check.py bin/arka_fetch_lyrics.py bin/arka_filter_images.py bin/arka_flow.py bin/arka_free_credits.py bin/arka_fugu.py bin/arka_gemini.py bin/arka_generate_data.py bin/arka_generate_image.py bin/arka_generate_music.py bin/arka_generate_thumbnail.py bin/arka_generate_video.py bin/arka_github_repo.py bin/arka_github_resume.py bin/arka_gmail_auto_draft.py bin/arka_google.py bin/arka_harvard_ark.py bin/arka_health_reading.py bin/arka_heartbeat.py bin/arka_hf_bridge.py bin/arka_human_docs.py bin/arka_infographic.py bin/arka_jsonkit.py bin/arka_kaggle.py bin/arka_kalshi.py bin/arka_llm_fallback.py bin/arka_llm_servers.py bin/arka_llm.py bin/arka_local_image_gen.py bin/arka_local_music_gen.py bin/arka_mac_mic.py bin/arka_macro_events.py bin/arka_markdown_style.py bin/arka_market_emotion.py bin/arka_mcp_server.py bin/arka_mcp.py bin/arka_media_qa.py bin/arka_media.py bin/arka_memory_detect.py bin/arka_memory.py bin/arka_message_sessions.py bin/arka_metallurgy.py bin/arka_model_advisor.py bin/arka_model_video.py bin/arka_network_proxy.py bin/arka_noise_remove.py bin/arka_open_url.py bin/arka_password_vault.py bin/arka_paths.py bin/arka_pdf_rag.py bin/arka_pdf_tools.py bin/arka_persona.py bin/arka_personalize.py bin/arka_phone.py bin/arka_platform.py bin/arka_play_website_game.py bin/arka_pr_check.py bin/arka_predict.py bin/arka_predictions.py bin/arka_profession_plugins.py bin/arka_profession_projects.py bin/arka_professions.py bin/arka_progress.py [2104 more files omitted for size] ``` ### Dependencies - desktop/package.json: @tauri-apps/cli@^2.5.0 - desktop/src-tauri/Cargo.toml: serde@1, serde_json@1, tauri@2, tauri-build@2 - desktop/ui/package.json: @types/react@^19.1.0, @types/react-dom@^19.1.0, @vitejs/plugin-react@^4.5.0, framer-motion@^13.0.0, fuse.js@^7.5.0, highlight.js@^11.11.1, lucide-react@^1.29.0, react@^19.1.0, react-dom@^19.1.0, react-markdown@^10.1.0, react-router-dom@^7.6.0, rehype-highlight@^7.0.2, remark-gfm@^4.0.1, sonner@^2.0.7, typescript@~5.8.3, vite@^6.3.5 - pyproject.toml: agno[groq,google,ollama]@>=2.5.0, apple-fm-sdk, arka-agent[chat,voice,pdf,pdf-tools,whatsapp,charts,drawings,video,3d,3d-ai,observability], beautifulsoup4, build@>=1.2, cryptography@>=42.0, ddgs, edge-tts@>=6.1, faker@>=24.0, feedparser@>=6.0, geopy, gradio_client@>=1.0, matplotlib@>=3.8, mcp@>=1.0, numpy@>=1.26, openai@>=1.0.0, openpyxl@>=3.1, opentelemetry-api@>=1.27.0, opentelemetry-exporter-otlp-proto-http@>=1.27.0, opentelemetry-sdk@>=1.27.0, Pillow@>=10.0, Pillow@>=10.0, Pillow@>=10.0, Pillow@>=10.0, Pillow@>=10.0, platformdirs@>=4.0, pyfiglet@>=1.0.0, pymupdf@>=1.24, pymupdf@>=1.24, pypdf@>=4.0, pytest, python-pptx@>=1.0, pywhatkit@>=5.4, qrcode@>=7.4, reportlab@>=4.0, requests, ruff, scikit-learn@>=1.4, selenium@>=4.0, sentence-transformers@>=3.0, sounddevice, sympy, trafilatura, trimesh@>=4.0, twine@>=5.0, vosk - requirements.txt: aiofiles@==25.1.0, altair@==6.1.0, annotated-types@==0.7.0, anyio@==4.11.0, aptdaemon@==2.0.2, arch@==8.0.0, argcomplete@==3.6.3, attrs@==25.4.0, autocommand@==2.2.2, babel@==2.17.0, bcc@==0.35.0, bcrypt@==5.0.0, beautifulsoup4@==4.14.3, blinker@==1.9.0, Brlapi@==0.8.6, Brotli@==1.2.0, cachetools@==7.0.6, certifi@==2026.1.4, cffi@==2.0.0, chardet@==5.2.0, charset-normalizer@==3.4.7, click@==8.1.8, command-not-found@==0.3, configobj@==5.0.9, contourpy@==1.3.3, courlan@==1.4.0, cryptography@==46.0.5, cssselect@==1.4.0, cups_of_caffeine@==2.9.14, cupshelpers@==1.0, curl_cffi@==0.15.0, cycler@==0.12.1, dasbus@==1.7, dateparser@==1.4.0, dbus-python@==1.4.0, ddgs@==9.14.4, decorator@==5.2.1, defer@==1.0.6, defusedxml@==0.7.1, distro@==1.9.0, distro-info@==1.15, dnspython@==2.8.0, docker@==7.1.0, email_validator@==2.2.0, ewmh@==0.1.6, fake-useragent@==2.2.0, fastapi@==0.118.0, feedparser@==6.0.12, fonttools@==4.61.1, frozendict@==2.4.7, galternatives@==1.0.10, geographiclib@==2.1, geopy@==2.4.1, ghp-import@==2.1.0, gitdb@==4.0.12, GitPython@==3.1.47, Glances@==4.3.3, greenlet@==3.3.2, h11@==0.16.0, h2@==4.3.0, hpack@==4.1.0, html5lib-modern@==1.2, htmldate@==1.10.0, httpcore@==1.0.9, httplib2@==0.22.0, httpx@==0.28.1, hyperframe@==6.1.0, idna@==3.11, inflect@==7.5.0, influxdb@==5.3.2, iniconfig@==2.1.0, itsdangerous@==2.2.0, jaraco.context@==6.0.1, jaraco.functools@==4.1.0, jaraco.text@==4.0.0, Jinja2@==3.1.6, joblib@==1.5.2, jsonpatch@==1.32, jsonpointer@==2.4, jsonschema@==4.19.2, jsonschema-specifications@==2023.12.1, jupyter_core@==5.9.1, jusText@==3.0.2, kagglehub@==1.0.1, kagglesdk@==0.1.27, kiwisolver@==1.4.10rc0, langtable@==0.0.69, language-selector@==0.1, launchpadlib@==2.1.0, lazr.restfulclient@==0.14.6, lazr.uri@==1.0.6, libevdev@==0.13.1, libpass@==1.9.3, libvirt-python@==12.0.0, linkify-it-py@==2.0.3, livereload@==2.7.1, louis@==3.36.0, lunr@==0.8.0, lxml@==6.1.1, lxml_html_clean@==0.4.5, lz4@==4.4.5+dfsg, Mako@==1.3.10.dev0, Markdown@==3.10.2, markdown-it-py@==3.0.0, MarkupSafe@==3.0.3, matplotlib@==3.10.7+dfsg1, mdurl@==0.1.2, mergedeep@==1.3.4, mkdocs@==1.6.1, mkdocs-get-deps@==0.2.0, more-itertools@==10.8.0, mpmath@==1.3.0, msgpack@==1.1.2, multitasking@==0.0.13, mutagen@==1.47.0, narwhals@==2.20.0, netaddr@==1.3.0, netifaces@==0.11.0, nltk@==3.9.2, numpy@==2.3.5, oauthlib@==3.3.1, olefile@==0.47, orjson@==3.11.5, packaging@==26.0, pandas@==3.0.2, pathspec@==1.0.4, patsy@==1.0.2, peewee@==4.0.5, pexpect@==4.9.0, pillow@==12.1.1, pipx@==1.8.0, platformdirs@==4.9.4, playwright@==1.60.0, pluggy@==1.6.0, pooch@==1.9.0, primp@==1.3.1, protobuf@==7.34.1, psutil@==7.1.0, ptyprocess@==0.7.0, pyarrow@==24.0.0, pyasn1@==0.6.3, pyasyncore@==1.0.2, PyAudio@==0.2.13, pycairo@==1.27.0, pycparser@==3.0, pycryptodomex@==3.20.0, pycups@==2.0.4, pydantic@==2.12.5, pydantic_core@==2.41.5, pydeck@==0.9.2, pyee@==13.0.1, pyenchant@==3.3.0, Pygments@==2.19.2, PyGObject@==3.56.2, pygooglenews@==0.1.3, pyinotify@==0.9.6, PyJWT@==2.10.1, pynvim@==0.6.0, pyparsing@==3.3.2, pyserial@==3.5, pysnmp@==7.1.21, pystache@==0.6.8, pytest@==9.0.2, python-apt@==3.1.0+ubuntu1, python-dateutil@==2.9.0.post0, python-debian@==1.0.1+ubuntu2, python-multipart@==0.0.20, python-xlib@==0.33, pytz@==2025.2, pyudev@==0.24.3, pyxdg@==0.28, PyYAML@==6.0.3, pyyaml_env_tag@==1.1, RapidFuzz@==3.12.2, referencing@==0.36.2, regex@==2025.9.18, requests@==2.32.5, rich@==13.9.4, rpds-py@==0.27.1, scikit-learn@==1.8.0, scipy@==1.16.3, setproctitle@==1.3.7, setuptools@==78.1.1, sgmllib3k@==1.0.0, shtab@==1.8.0, six@==1.17.0, smmap@==5.0.3, sniffio@==1.3.1, socksio@==1.0.0, soupsieve@==2.8.3, speedtest-cli@==2.1.3, starlette@==0.50.0, statsmodels@==0.14.6, streamlit@==1.56.0, sympy@==1.14.0, systemd-python@==235, tenacity@==9.1.4, textblob@==0.20.0, threadpoolctl@==3.6.0, tld@==0.13.2, toml@==0.10.2, tornado@==6.5.4, tqdm@==4.67.3, trafilatura@==2.1.0, traitlets@==5.14.3, typeguard@==4.4.4, typing_extensions@==4.15.0, typing-inspection@==0.4.2, tzlocal@==5.3.1, ubuntu-drivers-common@==0.0.0, ubuntu-pro-client@==8001, uc-micro-py@==1.0.3, ufoLib2@==0.18.1, ufw@==0.36.2, unattended-upgrades@==0.1, unicodedata2@==16.0.0, urllib3@==2.6.3, usb-creator@==0.3.16, userpath@==1.9.2, uvicorn@==0.38.0, uvloop@==0.22.1, vboxapi@==1, wadllib@==2.0.0, watchdog@==6.0.0, webencodings@==0.5.1, websockets@==16.0, wheel@==0.46.3, wsproto@==1.3.2, xdg@==5, xkit@==0.0.0, xlrd@==2.0.2, yfinance@==1.3.0, yt-dlp@==2026.3.17, zipp@==3.23.0, zopfli@==0.4.1 - speech-to-speech/pyproject.toml: ChatTTS@>=0.1.1, espeakng-loader@>=0.2.4, fastapi@>=0.115.0, faster-qwen3-tts@>=0.2.6, faster-whisper@>=1.0.3, funasr@>=1.1.6, httpx@>=0.28.0, kokoro@>=0.9.2, lightning-whisper-mlx@>=0.0.10, lingua-language-detector@>=2.0.2, lingua-language-detector@>=2.0.2, miniaudio@==1.61, misaki@>=0.9.4, mlx@==0.31.1, mlx-audio@==0.4.2, mlx-lm@==0.31.1, mlx-lm@==0.31.1, mlx-metal@==0.31.1, mlx-vlm@==0.4.1, modelscope@>=1.17.1, nano-parakeet@>=0.2.0, nltk@==3.9.4, numpy@>=1.26.0, onnxruntime@<1.24, openai@==2.28.0, phonemizer-fork@>=3.3.2, pillow@>=10.0.0, pocket-tts@>=0.1.0, pydantic@>=2.0, rich@>=13.0, scipy@>=1.10.0, sounddevice@>=0.5.0, soundfile@>=0.13.0, spacy@>=3.8.4, torch@>=2.4.0, torchaudio@>=2.4.0, transformers@>=4.57.0, transformers@>=4.57.0, uvicorn@>=0.30.0, websockets@>=12.0, websockets@>=12.0 ### Recent commits (newest first) - Draft changelog: week of August 17, 2026 (#10) - docs: translate en docs into cn and hi and expand nav (#9) - docs: normalize deploy guide headings to sentence case (#8) - Add to-folder routing, caches, output verify, and expanded skills. - Fix PyPI publish workflow with API token fallback. - Release v0.1.3 — bump version for PyPI publish. - Wire CodeRabbit into Arka for PR triggers and feedback fetch. - Add media skills, MCP expansion, design guides, and desktop landing work. - Add project_docs skill for first-person README and blog sync from git changes - Add daily reading, dev loop, predict/music skills, and Hindi docs. - Fix SigNoz judge pack links to use fork main. - Add SigNoz hackathon demo, blog, and chart NL/table features. - Add skills, observability, and docs improvements across the agent stack. - Add a GitHub star CTA to the README so visitors who find Arka useful can help others discover the project. - Improve chart install hints when matplotlib is missing. - Prefix chart CLI examples with `arka` in docs. - Add GitHub resume and productivity skills with docs SEO and observability. - Publish bundled SigNoz assets under signoz/ instead of gitignored hackathon/. - Add chart, treemap, and self-build skills with habitat routing. - improved devtools ## Key source files (fetched from GitHub, selected and truncated for size) ### CONTRIBUTING.md ```markdown # Contribution Guidelines We welcome contributions of all sizes — bug reports, docs fixes, new skills, and plugin ideas. This project aims to be **welcoming** and **inclusive**; please be respectful in issues and pull requests. ## Prerequisites - **Python** `3.11` or higher - **git** - Optional: [fish shell](https://fishshell.com) for the full 70+ skill router ## Local development ```bash git clone https://github.com/Sumit884-byte/arka.git cd arka python3 scripts/sync_bundled.py pip install -e ".[chat,dev]" cp .env.example ~/.config/arka/.env # add API keys as needed arka doctor ``` Run tests: ```bash pytest ``` ### Repository hygiene (editable checkouts) Runtime JSON, email contacts, MCP logs, and session state belong under **`.arka/`** in a git clone (or `~/.config/arka/` for installs) — not the repo root. Running `arka doctor` migrates scattered root files automatically. Do not commit `.env`, `your-secret-here` placeholders, `logs/`, `tmp/`, or ad-hoc `*-bug.md` reports. See [`docs/architecture/repository-layout.md`](docs/architecture/repository-layout.md) for the full layout. Refresh after pulling upstream: ```bash ./scripts/refetch.sh --install ``` ## Branching 1. Fork the repository and create a branch from `main`. 2. Make focused changes — one feature or fix per pull request. 3. Add or update tests when behavior changes. 4. Open a pull request with a clear description of what and why. ## Good first issues New to the codebase? Look for the **good first issue** label on [GitHub Issues](https://github.com/Sumit884-byte/arka/issues?q=label%3A%22good+first+issue%22). These are scoped tasks meant to help you learn the router, skills, and test layout without a steep ramp-up. ## Roadmap High-impact areas we are actively improving: - Symbolic routing coverage and plugin triggers - LLM provider failover and per-skill model profiles - Documentation at [arka-agent.mintlify.site](https://arka-agent.mintlify.site) - Chart, vision, and Google Workspace integrations Check open issues and discussions for the latest priorities before starting large work. By contributing, you agree that your contributions will be licensed under the project's **GPL-2.0** license. ## Publishing to PyPI The package name on PyPI is **`arka-agent`**. Publishing is handled by GitHub Actions (`.github/workflows/publish.yml`) on pushed tags matching `v*`, or manually via `scripts/publish_pypi.sh`. ### First-time PyPI setup (maintainers) 1. Register the project on [pypi.org](https://pypi.org/) (or claim `arka-agent` if reserved). 2. Configure **trusted publishing** on the PyPI project (after the first upload): - Open [arka-agent → Publishing](https://pypi.org/manage/project/arka-agent/settings/publishing/) - **Add a new publisher** → **GitHub** - Owner: `Sumit884-byte`, repository name: `arka`, workflow name: `publish.yml`, environment name: `pypi` - (Use *Pending publishers* under account settings only before the project exists on PyPI.) 3. In [truncated — 1198 more characters] ``` ### docs/AGENTS.md ```markdown > **First-time setup**: Customize this file for your project. Prompt the user to customize this file for their project. > For Mintlify product knowledge (components, configuration, writing standards), > install the Mintlify skill: `npx skills add https://mintlify.com/docs` # Documentation project instructions ## About this project - This is a documentation site built on [Mintlify](https://mintlify.com) - Pages are MDX files with YAML frontmatter - Configuration lives in `docs.json` - Use the Mintlify MCP server, `https://mcp.mintlify.com`, to edit content and settings via MCP - Use the Mintlify docs MCP server, `https://www.mintlify.com/docs/mcp`, to query information about using Mintlify via MCP ## Terminology {/* Add product-specific terms and preferred usage */} {/* Example: Use "workspace" not "project", "member" not "user" */} ## Style preferences {/* Add any project-specific style rules below */} - Use active voice and second person ("you") - Keep sentences concise — one idea per sentence - Use sentence case for headings - Bold for UI elements: Click **Settings** - Code formatting for file names, commands, paths, and code references ## Content boundaries {/* Define what should and shouldn't be documented */} {/* Example: Don't document internal admin features */} ``` ### Dockerfile ``` FROM python:3.13-slim ENV PYTHONDONTWRITEBYTECODE=1 \ PYTHONUNBUFFERED=1 \ ARKA_HOSTED_MODE=1 \ ARKA_REMOTE_PROFILE=coding \ ARKA_MCP_ENABLE_PERSONAL_SKILLS=0 \ REMOTE_HOST=0.0.0.0 WORKDIR /app RUN apt-get update \ && apt-get install -y --no-install-recommends git fish curl ca-certificates \ && rm -rf /var/lib/apt/lists/* COPY pyproject.toml README.md ./ COPY src ./src RUN pip install --no-cache-dir -e ".[dev]" EXPOSE 8765 CMD ["python", "-m", "arka.integrations.remote_server", "serve"] ``` ### docker-compose.yml ```yaml version: "3.8" services: arka: build: context: . dockerfile: Dockerfile image: arka:latest container_name: arka-server restart: unless-stopped ports: - "8765:8765" environment: - ARKA_HOSTED_MODE=1 - ARKA_REMOTE_PROFILE=coding - ARKA_MCP_ENABLE_PERSONAL_SKILLS=0 - REMOTE_HOST=0.0.0.0 - REMOTE_TOKEN=${REMOTE_TOKEN:-arka_cloud_secret_token} volumes: - arka_data:/root/.cache healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8765/v1/health"] interval: 30s timeout: 5s retries: 3 start_period: 10s volumes: arka_data: ``` ### pyproject.toml ``` [build-system] requires = ["setuptools>=68", "wheel"] build-backend = "setuptools.build_meta" [project] name = "arka-agent" version = "0.1.3" description = "Cross-platform AI agent — 70+ skills, MCP server, media tools, local-first routing" readme = "README.md" license = { text = "GPL-2.0-only" } requires-python = ">=3.11" authors = [{ name = "Sumit Mishra" }] keywords = ["ai", "agent", "cli", "assistant", "llm"] classifiers = [ "Development Status :: 4 - Beta", "Environment :: Console", "Intended Audience :: Developers", "License :: OSI Approved :: GNU General Public License v2 (GPLv2)", "Operating System :: OS Independent", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13", "Topic :: Utilities", ] dependencies = [ "platformdirs>=4.0", "cryptography>=42.0", "qrcode>=7.4", "feedparser>=6.0", ] [project.optional-dependencies] chat = [ "agno[groq,google,ollama]>=2.5.0", "openai>=1.0.0", "ddgs", "trafilatura", "beautifulsoup4", "sympy", "geopy", ] voice = [ "vosk", "sounddevice", ] pdf = [ "requests", ] pdf-tools = [ "pypdf>=4.0", "Pillow>=10.0", "reportlab>=4.0", "pymupdf>=1.24", ] charts = [ "matplotlib>=3.8", ] ascii = [ "pyfiglet>=1.0.0", ] data = [ "faker>=24.0", "openpyxl>=3.1", ] drawings = [ "Pillow>=10.0", "pymupdf>=1.24", ] video = [ "Pillow>=10.0", "edge-tts>=6.1", "python-pptx>=1.0", ] 3d = [ "numpy>=1.26", "trimesh>=4.0", ] 3d-ai = [ "gradio_client>=1.0", ] vision = [ "Pillow>=10.0", ] image-filter = [ "Pillow>=10.0", "sentence-transformers>=3.0", "scikit-learn>=1.4", ] whatsapp = [ "selenium>=4.0", "pywhatkit>=5.4", ] dev = [ "build>=1.2", "ruff", "pytest", "twine>=5.0", ] mcp-server = [ "mcp>=1.0", ] observability = [ "opentelemetry-api>=1.27.0", "opentelemetry-sdk>=1.27.0", "opentelemetry-exporter-otlp-proto-http>=1.27.0", ] apple-fm = [ "apple-fm-sdk", ] all = [ "arka-agent[chat,voice,pdf,pdf-tools,whatsapp,charts,drawings,video,3d,3d-ai,observability]", ] [project.scripts] arka = "arka.cli:main" arka-api = "arka.integrations.arka_api:main" [project.urls] Homepage = "https://github.com/Sumit884-byte/arka" Repository = "https://github.com/Sumit884-byte/arka" Documentation = "https://arka-agent.mintlify.site" Issues = "https://github.com/Sumit884-byte/arka/issues" [tool.pytest.ini_options] testpaths = ["tests"] addopts = "-ra" markers = [ "docker: requires Docker CLI and daemon", "docker_linux: Linux container integration tests", "docker_windows: Windows container integration tests", "windows_cli: Windows host CLI smoke tests", ] [tool.setuptools.packages.find] where = ["src"] [tool.setuptools.package-data] arka = [ "bundled/*.py", "bundled/*.example", "bundled/*.fish", "bundled/*.sh", "bundled/*.txt", "bundled/*.yaml", "bundled/*.html", "bundled/*.md", "bundled/privategpt/*", "bundled/aie/*", "bundled/whatsapp/*", "aie/*.py", "fish/config.fish", "fish/scripts/*", "requirements/*.txt", "pdf/privategpt/*", "env.example", "teams/templates/*", "agent/personas/templates/*", "skills/**/*", "professions/**/*", ] [tool.ruff.lint] # Optional-deps modules use lazy imports after env/setup (E402). ignore = ["E402"] ``` ### requirements.txt ``` aiofiles==25.1.0 altair==6.1.0 annotated-types==0.7.0 anyio==4.11.0 aptdaemon==2.0.2 arch==8.0.0 argcomplete==3.6.3 attrs==25.4.0 autocommand==2.2.2 babel==2.17.0 bcc==0.35.0 bcrypt==5.0.0 beautifulsoup4==4.14.3 blinker==1.9.0 Brlapi==0.8.6 Brotli==1.2.0 cachetools==7.0.6 certifi==2026.1.4 cffi==2.0.0 chardet==5.2.0 charset-normalizer==3.4.7 click==8.1.8 command-not-found==0.3 configobj==5.0.9 contourpy==1.3.3 courlan==1.4.0 cryptography==46.0.5 cssselect==1.4.0 cups_of_caffeine==2.9.14 cupshelpers==1.0 curl_cffi==0.15.0 cycler==0.12.1 dasbus==1.7 dateparser==1.4.0 dbus-python==1.4.0 ddgs==9.14.4 decorator==5.2.1 defer==1.0.6 defusedxml==0.7.1 distro==1.9.0 distro-info==1.15 dnspython==2.8.0 docker==7.1.0 email_validator==2.2.0 ewmh==0.1.6 fake-useragent==2.2.0 fastapi==0.118.0 feedparser==6.0.12 fonttools==4.61.1 frozendict==2.4.7 galternatives==1.0.10 geographiclib==2.1 geopy==2.4.1 ghp-import==2.1.0 gitdb==4.0.12 GitPython==3.1.47 Glances==4.3.3 greenlet==3.3.2 h11==0.16.0 h2==4.3.0 hpack==4.1.0 html5lib-modern==1.2 htmldate==1.10.0 httpcore==1.0.9 httplib2==0.22.0 httpx==0.28.1 hyperframe==6.1.0 idna==3.11 inflect==7.5.0 influxdb==5.3.2 iniconfig==2.1.0 itsdangerous==2.2.0 jaraco.context==6.0.1 jaraco.functools==4.1.0 jaraco.text==4.0.0 Jinja2==3.1.6 joblib==1.5.2 jsonpatch==1.32 jsonpointer==2.4 jsonschema==4.19.2 jsonschema-specifications==2023.12.1 jupyter_core==5.9.1 jusText==3.0.2 kagglehub==1.0.1 kagglesdk==0.1.27 kiwisolver==1.4.10rc0 langtable==0.0.69 language-selector==0.1 launchpadlib==2.1.0 lazr.restfulclient==0.14.6 lazr.uri==1.0.6 libevdev==0.13.1 libpass==1.9.3 libvirt-python==12.0.0 linkify-it-py==2.0.3 livereload==2.7.1 louis==3.36.0 lunr==0.8.0 lxml==6.1.1 lxml_html_clean==0.4.5 lz4==4.4.5+dfsg Mako==1.3.10.dev0 Markdown==3.10.2 markdown-it-py==3.0.0 MarkupSafe==3.0.3 matplotlib==3.10.7+dfsg1 mdurl==0.1.2 mergedeep==1.3.4 mkdocs==1.6.1 mkdocs-get-deps==0.2.0 more-itertools==10.8.0 mpmath==1.3.0 msgpack==1.1.2 multitasking==0.0.13 mutagen==1.47.0 narwhals==2.20.0 netaddr==1.3.0 netifaces==0.11.0 nltk==3.9.2 numpy==2.3.5 oauthlib==3.3.1 olefile==0.47 orjson==3.11.5 packaging==26.0 pandas==3.0.2 pathspec==1.0.4 patsy==1.0.2 peewee==4.0.5 pexpect==4.9.0 pillow==12.1.1 pipx==1.8.0 platformdirs==4.9.4 playwright==1.60.0 pluggy==1.6.0 pooch==1.9.0 primp==1.3.1 protobuf==7.34.1 psutil==7.1.0 ptyprocess==0.7.0 pyarrow==24.0.0 pyasn1==0.6.3 pyasyncore==1.0.2 PyAudio==0.2.13 pycairo==1.27.0 pycparser==3.0 pycryptodomex==3.20.0 pycups==2.0.4 pydantic==2.12.5 pydantic_core==2.41.5 pydeck==0.9.2 pyee==13.0.1 pyenchant==3.3.0 Pygments==2.19.2 PyGObject==3.56.2 pygooglenews==0.1.3 pyinotify==0.9.6 PyJWT==2.10.1 pynvim==0.6.0 pyparsing==3.3.2 pyserial==3.5 pysnmp==7.1.21 pystache==0.6.8 pytest==9.0.2 python-apt==3.1.0+ubuntu1 python-dateutil==2.9.0.post0 python-debian==1.0.1+ubuntu2 python-multipart==0.0.20 python-xlib==0.33 pytz==2025.2 pyudev==0.24.3 pyxdg==0.28 PyYAML==6.0.3 pyyaml_env_tag==1.1 RapidFuzz==3.12.2 referencing==0.36.2 regex==2025.9.18 requests==2.32.5 rich==13.9.4 rpds-py==0.27.1 scikit-learn==1.8.0 scipy==1.16.3 setproctitle==1.3.7 setuptools==78.1.1 sgmllib3k==1.0.0 shtab==1.8.0 six==1.17.0 smmap==5.0.3 sniffio==1.3.1 socksio==1.0.0 soupsieve==2.8.3 speedtest-cli==2.1.3 starlette==0.50.0 statsmodels==0.14.6 streamlit==1.56.0 sympy==1.14.0 systemd-python==235 tenacity==9.1.4 textblob==0.20.0 threadpoolctl==3.6.0 tld==0.13.2 toml==0.10.2 tornado==6.5.4 tqdm==4.67.3 trafilatura==2.1.0 traitlets==5.14.3 typeguard==4.4.4 typing-inspection==0.4.2 typing_extensions==4.15.0 tzlocal==5.3.1 ubuntu-drivers-common==0.0.0 ubuntu-pro-client==8001 uc-micro-py==1.0.3 ufoLib2==0.18.1 ufw==0.36.2 unattended-upgrades==0.1 unicodedata2==16.0.0 urllib3==2.6.3 usb-creator==0.3.16 userpath==1.9.2 uvicorn==0.38.0 uvloop==0.22.1 vboxapi==1 wadllib==2.0.0 watchdog==6.0.0 webencodings==0.5.1 websockets==16.0 wheel==0.46.3 wsproto==1.3.2 xdg==5 xkit==0.0.0 xlrd==2.0.2 yfinance==1.3.0 yt-dlp==2026.3.17 zipp==3.23.0 zopfli==0.4.1 ``` ### speech-to-speech/Dockerfile ``` FROM pytorch/pytorch:2.4.0-cuda12.1-cudnn9-devel ENV PYTHONUNBUFFERED 1 ENV PATH="/usr/src/app/.venv/bin:${PATH}" WORKDIR /usr/src/app # Install packages RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/* RUN pip install --no-cache-dir uv COPY pyproject.toml ./ RUN uv sync --no-install-project --no-dev COPY . . RUN uv sync --no-dev ``` ### desktop/package.json ``` { "name": "arka-desktop", "private": true, "version": "0.1.0", "description": "Arka local desktop app (Tauri)", "scripts": { "dev": "tauri dev", "build": "tauri build", "ui:dev": "npm run dev --prefix ui", "ui:build": "npm run build --prefix ui", "bridge": "python3 bridge.py" }, "devDependencies": { "@tauri-apps/cli": "^2.5.0" } } ``` ### speech-to-speech/docker-compose.yml ```yaml --- services: pipeline: build: context: . dockerfile: ${DOCKERFILE:-Dockerfile} command: - python3 - s2s_pipeline.py - --recv_host - 0.0.0.0 - --send_host - 0.0.0.0 - --model_name - microsoft/Phi-3-mini-4k-instruct - --init_chat_role - system - --init_chat_prompt - "You are a helpful assistant" - --stt_compile_mode - reduce-overhead expose: - 12345/tcp - 12346/tcp ports: - 12345:12345/tcp - 12346:12346/tcp volumes: - ./cache/:/root/.cache/ - ./s2s_pipeline.py:/usr/src/app/s2s_pipeline.py deploy: resources: reservations: devices: - driver: nvidia device_ids: ['0'] capabilities: [gpu] ``` ### speech-to-speech/pyproject.toml ``` [build-system] requires = ["setuptools>=77.0.3", "wheel"] build-backend = "setuptools.build_meta" [project] name = "speech-to-speech" version = "0.2.10" description = "Low-latency speech-to-speech pipeline" readme = "README.md" requires-python = ">=3.10" license = "Apache-2.0" license-files = ["LICENSE"] authors = [ { name = "Hugging Face" }, ] keywords = ["speech-to-speech", "voice-agents", "speech-recognition", "text-to-speech", "openai"] classifiers = [ "Development Status :: 3 - Alpha", "Intended Audience :: Developers", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", "Topic :: Multimedia :: Sound/Audio :: Speech", "Topic :: Scientific/Engineering :: Artificial Intelligence", ] dependencies = [ "fastapi>=0.115.0", "httpx>=0.28.0", "nltk==3.9.4", "numpy>=1.26.0,<2.4.4; platform_system == 'Darwin'", "numpy>=1.26.0; platform_system != 'Darwin'", "openai==2.28.0", "pillow>=10.0.0", "pydantic>=2.0", "rich>=13.0", "scipy>=1.10.0", "sounddevice==0.5.3; platform_system == 'Darwin'", "sounddevice>=0.5.0; platform_system != 'Darwin'", "soundfile>=0.13.0; platform_system == 'Darwin'", "torch==2.11.0; platform_system == 'Darwin'", "torch>=2.4.0; platform_system != 'Darwin'", "torchaudio==2.11.0; platform_system == 'Darwin'", "torchaudio>=2.4.0; platform_system != 'Darwin'", "transformers==5.6.2; platform_system == 'Darwin'", "transformers>=4.57.0; platform_system != 'Darwin'", "uvicorn>=0.30.0", "websockets>=12.0", "nano-parakeet>=0.2.0; platform_system != 'Darwin'", "faster-qwen3-tts>=0.2.6; platform_system != 'Darwin'", "lingua-language-detector>=2.0.2", "miniaudio==1.61; platform_system == 'Darwin'", "mlx==0.31.1; platform_system == 'Darwin'", "mlx-audio==0.4.2; platform_system == 'Darwin'", "mlx-lm==0.31.1; platform_system == 'Darwin'", "mlx-metal==0.31.1; platform_system == 'Darwin'", "misaki>=0.9.4; platform_system == 'Darwin'", "espeakng-loader>=0.2.4; platform_system == 'Darwin'", "spacy>=3.8.4; platform_system == 'Darwin'", "phonemizer-fork>=3.3.2; platform_system == 'Darwin'", ] [project.optional-dependencies] chattts = [ "ChatTTS>=0.1.1", ] facebook-mms = [ "transformers>=4.57.0", ] faster-whisper = [ "faster-whisper>=1.0.3", ] kokoro = [ "kokoro>=0.9.2; platform_system != 'Darwin'", ] language-detection = [ "lingua-language-detector>=2.0.2", ] mlx-lm = [ "mlx-lm==0.31.1; platform_system == 'Darwin'", "mlx-vlm==0.4.1; platform_system == 'Darwin'", ] paraformer = [ "funasr>=1.1.6", "modelscope>=1.17.1", "onnxruntime<1.24; python_version < '3.11'", ] pocket = [ "pocket-tts>=0.1.0", ] websocket = [ "websockets>=12.0", ] whisper-mlx = [ "lightning-whisper-mlx>=0.0.10; platform_system == 'Darwin'", ] [project.urls] Homepage = "https://github.com/huggingface/speech-to-speech" Repository = "https://github.com/huggingface/speech-to-speech" Issues = "https://github.com/huggingface/speech-to-speech/issues" [project.scripts] speech-to-speech = "speech_to_speech.s2s_pipeline:main" [dependency-groups] dev = [ "ruff", "mypy", "pytest", "pytest-asyncio", "websockets>=12.0", ] [tool.pytest.ini_options] asyncio_mode = "auto" [tool.uv] package = true prerelease = "allow" [tool.setuptools.packages.find] where = ["src"] include = ["speech_to_speech*"] exclude = ["tests*"] [tool.setuptools.package-data] speech_to_speech = ["TTS/*.wav"] [tool.ruff] src = ["src"] line-length = 120 [tool.ruff.lint] select = ["E", "F", "I", "W"] ignore = ["E501"] [tool.mypy] python_version = "3.10" ignore_missing_imports = true warn_unused_configs = true check_untyped_defs = false ``` [1939 more indexed source files omitted to keep this export small. The full file list is in the Codebase structure section above.]