Update v0.1 handoff README
This commit is contained in:
Codex
parent
2501e86a80
commit
ec8ba8dff8
1 changed files with 153 additions and 35 deletions
188
README.md
188
README.md
|
|
@ -2,74 +2,192 @@
|
|||
|
||||
Slide Factory turns messy business content into brand-consistent slide decks.
|
||||
|
||||
The first build is intentionally local-first: a CLI, an API, and a small web UI
|
||||
share the same deck spec, style packs, and PPTX renderer. The same core contract
|
||||
can later run behind `dev.slides.scottfelten.com` and `slides.scottfelten.com`.
|
||||
**Current version:** v0.1 local source-upload MVP
|
||||
**Primary dev machine:** MBS / Mac Studio
|
||||
**Local source:** `/Users/tars/AgentPlane/projects/slide-factory/source/slide-factory`
|
||||
**Forgejo:** `https://git.scottfelten.com/tars/slide-factory.git`
|
||||
**Current branch:** `dev`
|
||||
|
||||
The web UI is source-first: paste notes, drop a file, choose a file, or paste an
|
||||
image into the source area. The MVP extracts text from Markdown/text, PDF, and
|
||||
PPTX files. Image upload starts a deck from image metadata today; vision/OCR is
|
||||
reserved for the Model Service Gateway integration.
|
||||
## What Works In v0.1
|
||||
|
||||
## MVP Contract
|
||||
The app can create an editable PPTX from:
|
||||
|
||||
- pasted markdown or plain text
|
||||
- `.md`, `.markdown`, or `.txt` files
|
||||
- `.pdf` files with extractable text
|
||||
- `.pptx` files by extracting slide text
|
||||
- image files or pasted clipboard images as starter context
|
||||
|
||||
The v0.1 deck-generation path is:
|
||||
|
||||
```text
|
||||
source content
|
||||
-> content extraction
|
||||
-> deck planning
|
||||
-> text extraction
|
||||
-> heuristic deck planning
|
||||
-> validated DeckSpec
|
||||
-> brand/style pack
|
||||
-> Incorta starter style pack
|
||||
-> PPTX renderer
|
||||
-> saved artifacts
|
||||
-> saved PPTX + DeckSpec JSON
|
||||
```
|
||||
|
||||
The LLM layer should produce structured thinking, not freehand slide design.
|
||||
Renderers consume a validated `DeckSpec` and a `StylePack`.
|
||||
This is deliberately local-first. It proves the core source-to-deck loop before
|
||||
production hosting, auth, persistence, or full LLM orchestration.
|
||||
|
||||
## Quick Start
|
||||
## Quick Start On MBS
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run sample
|
||||
cd /Users/tars/AgentPlane/projects/slide-factory/source/slide-factory
|
||||
zsh -lc "npm install"
|
||||
```
|
||||
|
||||
Outputs are written to:
|
||||
Run the API:
|
||||
|
||||
```bash
|
||||
zsh -lc "SLIDE_FACTORY_PORT=3025 SLIDE_FACTORY_OUTPUT_DIR=outputs npm run dev:api"
|
||||
```
|
||||
|
||||
Run the web app in a second terminal:
|
||||
|
||||
```bash
|
||||
cd /Users/tars/AgentPlane/projects/slide-factory/source/slide-factory
|
||||
zsh -lc "npm run dev:web"
|
||||
```
|
||||
|
||||
Open on MBS:
|
||||
|
||||
```text
|
||||
http://127.0.0.1:5185/
|
||||
```
|
||||
|
||||
If using the MBA to view the MBS app, open an SSH tunnel from the MBA:
|
||||
|
||||
```bash
|
||||
ssh -L 5185:127.0.0.1:5185 -L 3025:127.0.0.1:3025 tars-ts
|
||||
```
|
||||
|
||||
Then open on the MBA:
|
||||
|
||||
```text
|
||||
http://127.0.0.1:5185/
|
||||
```
|
||||
|
||||
## Current Running Dev Server
|
||||
|
||||
If the previous session left the app running, the process metadata is here:
|
||||
|
||||
```text
|
||||
/tmp/slide-factory-dev/api.pid
|
||||
/tmp/slide-factory-dev/web.pid
|
||||
/tmp/slide-factory-dev/api.log
|
||||
/tmp/slide-factory-dev/web.log
|
||||
```
|
||||
|
||||
Stop it with:
|
||||
|
||||
```bash
|
||||
kill $(cat /tmp/slide-factory-dev/api.pid) $(cat /tmp/slide-factory-dev/web.pid)
|
||||
```
|
||||
|
||||
Check ports:
|
||||
|
||||
```bash
|
||||
lsof -nP -iTCP:3025 -sTCP:LISTEN
|
||||
lsof -nP -iTCP:5185 -sTCP:LISTEN
|
||||
```
|
||||
|
||||
## CLI Smoke
|
||||
|
||||
```bash
|
||||
zsh -lc "npm run sample"
|
||||
```
|
||||
|
||||
Outputs:
|
||||
|
||||
```text
|
||||
outputs/sample-incorta.pptx
|
||||
outputs/sample-incorta.deck.json
|
||||
```
|
||||
|
||||
Run the local API:
|
||||
## API Smoke
|
||||
|
||||
```bash
|
||||
npm run dev:api
|
||||
curl -sS http://127.0.0.1:3025/api/health
|
||||
```
|
||||
|
||||
Run the web shell:
|
||||
Upload a source file:
|
||||
|
||||
```bash
|
||||
npm run dev:web
|
||||
curl -sS -X POST http://127.0.0.1:3025/api/decks/from-source \
|
||||
-F style=incorta \
|
||||
-F instructions="Create a concise executive deck." \
|
||||
-F source=@examples/customer-discovery.md
|
||||
```
|
||||
|
||||
Then open:
|
||||
## Repo Structure
|
||||
|
||||
```text
|
||||
http://127.0.0.1:5185
|
||||
apps/
|
||||
api/ Express API and source extraction
|
||||
cli/ Local deck creation command
|
||||
web/ React/Vite source-first UI
|
||||
packages/
|
||||
core/ schemas, style loading, heuristic planner
|
||||
render-pptx/ deterministic PPTX renderer
|
||||
styles/
|
||||
incorta/ starter Incorta style pack
|
||||
examples/
|
||||
customer-discovery.md
|
||||
docs/
|
||||
architecture.md
|
||||
```
|
||||
|
||||
Supported starter sources:
|
||||
## Important Limits
|
||||
|
||||
- `.md`, `.markdown`, `.txt`
|
||||
- `.pdf`
|
||||
- `.pptx`
|
||||
- image files or pasted clipboard images
|
||||
- Image upload does not yet perform OCR or vision understanding. It creates a
|
||||
starter deck from image metadata and the user instructions.
|
||||
- PDF extraction is text-only. Scanned/image-only PDFs need future OCR.
|
||||
- The planner is heuristic. Model Service Gateway/LLM integration is not wired
|
||||
in yet.
|
||||
- Generated slides are editable PPTX, but automated visual QA is still basic.
|
||||
- No auth, persistence, job history, hosted route, or Google Slides mutation yet.
|
||||
- Do not commit raw customer docs, transcripts, tokens, provider keys, or private
|
||||
Drive files.
|
||||
|
||||
## AgentPlane Notes
|
||||
## AgentPlane Rules
|
||||
|
||||
- Implementation truth should live in Forgejo.
|
||||
- Forgejo is implementation truth.
|
||||
- Runtime secrets must come from scoped projections or Model Service Gateway.
|
||||
- Do not commit raw source data, tokens, refresh tokens, or customer documents.
|
||||
- Google Slides generation should reuse the existing AgentPlane guidance:
|
||||
copy templates, inventory native containers, fill existing object IDs, and
|
||||
render thumbnails/contact sheets before handoff.
|
||||
- New production deploy, DNS, nginx, systemd, OAuth, secret projection, or
|
||||
provider-key work requires explicit approval.
|
||||
- Google Slides generation should reuse:
|
||||
|
||||
```text
|
||||
/Users/tars/AgentPlane/projects/google-slides
|
||||
```
|
||||
|
||||
For branded Google Slides, use brand-safe mode: copy the template, inventory
|
||||
native containers, fill existing object IDs, delete unused slides, and render
|
||||
thumbnails/contact sheets for visual QA.
|
||||
|
||||
## Suggested Next Session
|
||||
|
||||
Start here:
|
||||
|
||||
```bash
|
||||
cd /Users/tars/AgentPlane/projects/slide-factory/source/slide-factory
|
||||
git status --short --branch
|
||||
git pull --ff-only origin dev
|
||||
zsh -lc "npm install && npm run build"
|
||||
```
|
||||
|
||||
Recommended v0.2 priorities:
|
||||
|
||||
1. Add Model Service Gateway integration for source understanding and deck
|
||||
planning without raw provider keys in the app.
|
||||
2. Add OCR/vision path for images and scanned PDFs.
|
||||
3. Add SQLite job history and artifact metadata.
|
||||
4. Add strict DeckSpec validation for external/LLM-generated specs.
|
||||
5. Add PPTX visual QA: render thumbnails or PDF previews and catch overflow.
|
||||
6. Add style-pack save/load workflow and template import.
|
||||
7. Add Google Slides renderer using the existing template-container workflow.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue