How griv32/proposal-generator works
Project Type and Purpose
• This is an open-source, Python-based CLI tool (“Proposal Generator”) that ingests discovery-call transcript files, invokes the OpenAI API to generate structured business proposals, and outputs markdown/JSON files. It’s a command-line workflow engine, not a multi-tier web app.
High-Level File-Structure Analysis
• Top-level:
• src/proposal_generator/ – core modules (CLI, workflow, processors, models, formatter)
• run_* and example_*.py scripts – sample entry points
• sample_data/ – example transcripts
• docs/ – API and developer docs
• CI/CD configs and linting/security tools in .github/, .bandit, .pre-commit-config.yaml, etc.
• Tests mirror the core modules under tests/, verifying each component.
Key Modules & Responsibilities
• CLI (cli.py): Parses command-line args (Click), loads env, dispatches to ProposalWorkflow.
• Workflow (workflow.py): Orchestrates the end-to-end pipeline:
a. Load transcript (file or text)
b. TranscriptionProcessor – cleans/splits the text
c. ProposalGenerator – assembles prompts, calls OpenAI API (via LangChain or direct HTTP)
d. OutputFormatter – builds Markdown/JSON, writes to disk
• Models (models.py): Pydantic schemas for inputs/outputs and validation.
External Dependencies & Storage
• Environment/config: .env or env vars for OpenAI API Key, model, log level
• External Service: OpenAI GPT API (via LangChain or direct REST)
• Local FS:
• Input transcripts (--input, sample_data/)
• Output folder (--output for .md and .json)
a. CLI Layer
• proposal-generator executable (Click)
• Example runners (run_example.py, run_proposal_generator.py)
b. Core Pipeline
• ProposalWorkflow (orchestrator)
• TranscriptionProcessor
• ProposalGenerator
• OutputFormatter
• Models (validation)
c. External Services
• OpenAI GPT API
d. Persistence
• Local File System for inputs/outputs
e. Configuration
• Env Vars / .env loader
Relationships & Data Flow
1. User invokes CLI →
2. CLI parses args & reads transcript file →
3. Workflow calls TranscriptionProcessor → cleans/splits text →
4. Workflow calls ProposalGenerator → sends prompt/data to OpenAI →
5. OpenAI returns generated content →
6. Workflow calls OutputFormatter → writes .md and .json →
7. CLI reports success/failure
Architectural Patterns & Principles
• Pipeline / Chain of Responsibility: each module has a single responsibility.
• Dependency Injection: CLI wires in Workflow and modules.
• Modular, testable components with Pydantic models.
• External-service abstraction (isolated call to OpenAI).