Flatten source modules to root with layered naming

Author: ArietidsZ

PROJECT_STRUCTURE.md

@@ -1,19 +1,19 @@
 # Project Structure
 
-Only the files listed below are retained. Any file not listed here must be removed.
+All source files are in the workspace root. Layering is preserved by filename prefix.
 
 /.gitignore
 /.data/
 /README.md
 /PROJECT_STRUCTURE.md
 /pyproject.toml
-/vra/__init__.py
-/vra/__main__.py
-/vra/config.py
-/vra/media.py
-/vra/transcribe.py
-/vra/summarize.py
-/vra/storage.py
-/vra/rss.py
-/vra/pipeline.py
-/vra/api.py
+/vra.py
+/cli.py
+/core_config.py
+/service_media.py
+/service_transcribe.py
+/service_summarize.py
+/service_pipeline.py
+/adapter_api.py
+/adapter_rss.py
+/adapter_storage.py

README.md

@@ -34,6 +34,16 @@ python -m vra serve --bind 0.0.0.0:8080
 
 Models are downloaded from Hugging Face automatically on first run.
 
+## Project Layout
+
+The codebase is organized by layer and naming prefix in the project root:
+
+- `core_*.py`: core runtime config (`core_config.py`)
+- `service_*.py`: media preparation, transcription, summarization, and orchestration
+- `adapter_*.py`: FastAPI interface, RSS rendering, and database adapter
+- `cli.py`: CLI commands (`serve`, `verify`)
+- `vra.py`: module entry for `python -m vra`
+
 ## Environment Variables
 
 | Variable | Default | Description |

vra/api.py adapter_api.pyvra/api.py renamed to adapter_api.py

@@ -4,11 +4,11 @@
 from dataclasses import asdict
 from datetime import datetime, timezone
 
-from fastapi import Depends, FastAPI, Header, HTTPException, Query, Request
-from fastapi.responses import PlainTextResponse, Response
+from fastapi import Depends, FastAPI, Header, HTTPException, Query
+from fastapi.responses import Response
 from pydantic import BaseModel
 
-from .pipeline import Pipeline
+from service_pipeline import Pipeline
 
 
 class IngestRequest(BaseModel):
@@ -29,7 +29,9 @@ def create_app(pipeline: Pipeline, api_key: str | None = None) -> FastAPI:
     rss_link = os.environ.get("VRA_RSS_LINK", "http://localhost:8080/rss")
     rss_desc = os.environ.get("VRA_RSS_DESCRIPTION", "Video summaries")
 
-    def _check_auth(authorization: str | None = Header(None), x_api_key: str | None = Header(None)):
+    def _check_auth(
+        authorization: str | None = Header(None), x_api_key: str | None = Header(None)
+    ):
         if api_key is None:
             return
         token = None
@@ -57,7 +59,9 @@ async def process(req: ProcessRequest, _=Depends(_check_auth)):
         return {
             "source_url": report.source_url,
             "title": report.title,
-            "transcription": asdict(report.transcription) if report.transcription else None,
+            "transcription": asdict(report.transcription)
+            if report.transcription
+            else None,
             "summary": asdict(report.summary) if report.summary else None,
         }
 

vra/rss.py adapter_rss.pyvra/rss.py renamed to adapter_rss.py

@@ -3,7 +3,7 @@
 from datetime import datetime, timezone
 from xml.etree.ElementTree import Element, SubElement, tostring
 
-from .storage import SummaryRecord
+from adapter_storage import SummaryRecord
 
 
 def render_feed(
@@ -32,7 +32,9 @@ def render_feed(
         if rec.published_at:
             SubElement(item, "pubDate").text = _rfc2822(rec.published_at)
 
-    return '<?xml version="1.0" encoding="UTF-8"?>\n' + tostring(rss, encoding="unicode")
+    return '<?xml version="1.0" encoding="UTF-8"?>\n' + tostring(
+        rss, encoding="unicode"
+    )
 
 
 def _rfc2822(dt: datetime) -> str:

vra/storage.py adapter_storage.pyvra/storage.py renamed to adapter_storage.py

@@ -8,8 +8,8 @@
 
 import asyncpg
 
-from .transcribe import TranscriptionResult
-from .summarize import SummaryResult
+from service_summarize import SummaryResult
+from service_transcribe import TranscriptionResult
 
 log = logging.getLogger(__name__)
 
@@ -78,7 +78,9 @@ async def upsert_feed(self, url: str, title: str | None) -> uuid.UUID:
                    DO UPDATE SET title = COALESCE(EXCLUDED.title, feeds.title),
                                  last_checked = NOW()
                    RETURNING id""",
-                fid, url, title,
+                fid,
+                url,
+                title,
             )
         return row["id"]
 
@@ -102,17 +104,27 @@ async def upsert_video(
                        guid = COALESCE(EXCLUDED.guid, videos.guid),
                        feed_id = COALESCE(EXCLUDED.feed_id, videos.feed_id)
                    RETURNING id""",
-                vid, feed_id, source_url, guid, title, published_at,
+                vid,
+                feed_id,
+                source_url,
+                guid,
+                title,
+                published_at,
             )
         return row["id"]
 
-    async def insert_transcript(self, video_id: uuid.UUID, tr: TranscriptionResult) -> uuid.UUID:
+    async def insert_transcript(
+        self, video_id: uuid.UUID, tr: TranscriptionResult
+    ) -> uuid.UUID:
         tid = uuid.uuid4()
         async with self._pool.acquire() as conn:
             await conn.execute(
                 """INSERT INTO transcripts (id, video_id, language, text)
                    VALUES ($1, $2, $3, $4)""",
-                tid, video_id, tr.language, tr.text,
+                tid,
+                video_id,
+                tr.language,
+                tr.text,
             )
         return tid
 
@@ -122,7 +134,10 @@ async def insert_summary(self, video_id: uuid.UUID, sr: SummaryResult) -> uuid.U
             await conn.execute(
                 """INSERT INTO summaries (id, video_id, summary, key_points)
                    VALUES ($1, $2, $3, $4::jsonb)""",
-                sid, video_id, sr.summary, json.dumps(sr.key_points),
+                sid,
+                video_id,
+                sr.summary,
+                json.dumps(sr.key_points),
             )
         return sid
 
@@ -142,12 +157,14 @@ async def latest_summaries(self, limit: int = 20) -> list[SummaryRecord]:
             kp = r["key_points"]
             if isinstance(kp, str):
                 kp = json.loads(kp)
-            out.append(SummaryRecord(
-                title=r["title"],
-                source_url=r["source_url"],
-                published_at=r["published_at"],
-                summary=r["summary"],
-                key_points=kp if isinstance(kp, list) else [],
-                created_at=r["created_at"],
-            ))
+            out.append(
+                SummaryRecord(
+                    title=r["title"],
+                    source_url=r["source_url"],
+                    published_at=r["published_at"],
+                    summary=r["summary"],
+                    key_points=kp if isinstance(kp, list) else [],
+                    created_at=r["created_at"],
+                )
+            )
         return out

vra/__main__.py cli.pyvra/__main__.py renamed to cli.py

@@ -7,14 +7,14 @@
 import click
 import uvicorn
 
-from .config import Config
+from core_config import Config
 
 log = logging.getLogger(__name__)
 
 
 @click.group()
 def cli():
-    """Video RSS Aggregator — Qwen3 intelligent video summarization."""
+    """Video RSS Aggregator - Qwen3 intelligent video summarization."""
     logging.basicConfig(
         level=logging.INFO,
         format="%(asctime)s %(levelname)s [%(name)s] %(message)s",
@@ -34,8 +34,8 @@ def serve(bind: str | None):
         host, port = config.bind_host, config.bind_port
 
     async def _run():
-        from .api import create_app
-        from .pipeline import Pipeline
+        from adapter_api import create_app
+        from service_pipeline import Pipeline
 
         pipeline = await Pipeline.create(config)
         app = create_app(pipeline, config.api_key)
@@ -48,7 +48,9 @@ async def _run():
 
 @cli.command()
 @click.option("--feed-url", envvar="VRA_VERIFY_FEED_URL", required=True)
-@click.option("--source", envvar="VRA_VERIFY_SOURCE", required=True, help="Audio path or URL")
+@click.option(
+    "--source", envvar="VRA_VERIFY_SOURCE", required=True, help="Audio path or URL"
+)
 def verify(feed_url: str, source: str):
     """Run end-to-end verification with real data."""
     import json
@@ -57,7 +59,7 @@ def verify(feed_url: str, source: str):
     config = Config.from_env()
 
     async def _run():
-        from .pipeline import Pipeline
+        from service_pipeline import Pipeline
 
         pipeline = await Pipeline.create(config)
 
@@ -76,7 +78,7 @@ async def _run():
         process_ms = int((time.monotonic() - t2) * 1000)
 
         t3 = time.monotonic()
-        rss = await pipeline.rss_feed("Verification", feed_url, "test", 10)
+        await pipeline.rss_feed("Verification", feed_url, "test", 10)
         rss_ms = int((time.monotonic() - t3) * 1000)
 
         total_ms = int((time.monotonic() - t0) * 1000)
@@ -85,8 +87,12 @@ async def _run():
             "feed_url": feed_url,
             "feed_items": feed_report.item_count,
             "processed_source": source,
-            "transcription_chars": len(proc_report.transcription.text) if proc_report.transcription else 0,
-            "summary_chars": len(proc_report.summary.summary) if proc_report.summary else 0,
+            "transcription_chars": len(proc_report.transcription.text)
+            if proc_report.transcription
+            else 0,
+            "summary_chars": len(proc_report.summary.summary)
+            if proc_report.summary
+            else 0,
             "total_ms": total_ms,
             "feed_ms": feed_ms,
             "process_ms": process_ms,
@@ -95,7 +101,3 @@ async def _run():
         print(json.dumps(report, indent=2))
 
     asyncio.run(_run())
-
-
-if __name__ == "__main__":
-    cli()

vra/config.py core_config.pyvra/config.py renamed to core_config.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import os
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 
 
 @dataclass(frozen=True, slots=True)

pyproject.toml

@@ -18,11 +18,22 @@ dependencies = [
 ]
 
 [project.scripts]
-vra = "vra.__main__:cli"
+vra = "cli:cli"
 
 [build-system]
 requires = ["setuptools>=75"]
 build-backend = "setuptools.build_meta"
 
-[tool.setuptools.packages.find]
-include = ["vra*"]
+[tool.setuptools]
+py-modules = [
+    "vra",
+    "cli",
+    "core_config",
+    "service_media",
+    "service_transcribe",
+    "service_summarize",
+    "service_pipeline",
+    "adapter_api",
+    "adapter_rss",
+    "adapter_storage",
+]

vra/media.py service_media.pyvra/media.py renamed to service_media.py

@@ -1,21 +1,17 @@
 from __future__ import annotations
 
 import asyncio
-import logging
-from dataclasses import dataclass, field
-from io import BytesIO
+from dataclasses import dataclass
 
 import feedparser
 import httpx
 
-from .config import Config
-from .media import prepare_audio
-from .rss import render_feed
-from .storage import Database
-from .summarize import SummarizationEngine, SummaryResult
-from .transcribe import TranscriptionEngine, TranscriptionResult
-
-log = logging.getLogger(__name__)
+from adapter_rss import render_feed
+from adapter_storage import Database
+from core_config import Config
+from service_media import prepare_audio
+from service_summarize import SummarizationEngine, SummaryResult
+from service_transcribe import TranscriptionEngine, TranscriptionResult
 
 
 @dataclass(slots=True)
@@ -52,16 +48,11 @@ async def create(cls, config: Config) -> Pipeline:
         db = await Database.connect(config.database_url)
         await db.migrate()
 
-        # Load models in background threads to keep event loop responsive
         transcriber = await asyncio.to_thread(TranscriptionEngine.get, config)
         summarizer = await asyncio.to_thread(SummarizationEngine.get, config)
 
         return cls(config, db, transcriber, summarizer)
 
-    # ------------------------------------------------------------------
-    # Public API
-    # ------------------------------------------------------------------
-
     async def ingest_feed(
         self,
         feed_url: str,
@@ -115,10 +106,6 @@ async def rss_feed(
         records = await self._db.latest_summaries(limit)
         return render_feed(title, link, description, records)
 
-    # ------------------------------------------------------------------
-    # Internal
-    # ------------------------------------------------------------------
-
     async def _process_with_video(
         self,
         video_id,
@@ -146,11 +133,6 @@ async def _process_with_video(
         )
 
 
-# ------------------------------------------------------------------
-# Helpers
-# ------------------------------------------------------------------
-
-
 def _pick_source_url(entry) -> str | None:
     enclosures = entry.get("enclosures", [])
     if enclosures: