speak2py 0.1

MVP: Load CSV/Excel/JSON into a pandas DataFrame via speak2py()

Speak2Py

Version: MVP v0.1

---

🎯 Objective

Let users run any Python logic—data loading, analysis, plotting, even algorithm, data structures generation—by writing plain-English commands. The MVP proves out:

• English→Python translation via a hosted AI (Gemini on Vertex AI)
• Safe execution of the generated code and return of results
• Zero-config UX: no local AI models, no credentials, just install and run

---

📝 Overview

Speak2Py accepts natural-language prompts such as:

• “read file ‘data.csv’ and head 5”
• “plot x vs y from ‘data.csv’”
• “generate prime numbers up to 100 and assign to result”

Behind the scenes it:

1. Sends your prompt to a hosted FastAPI service on Cloud Run
2. Calls Gemini to produce a Python snippet assigning its output to result
3. Executes that snippet in a sandboxed namespace
4. Serializes and returns result as a DataFrame, list, or plot

End users simply:

pip install speak2py

---

MVP Features (v0.1)

1. Natural-Language Commands

   • CLI:

     speak2py "read file 'data.csv' and head 5" --show
     

   • Python API:

     from speak2py import speak2py
     df = speak2py("load 'data.csv' and describe")
     

2. AI-Driven Code Generation

   • Sends your English prompt to a hosted Gemini/Vertex AI service
   • Automatically generates and executes a Python snippet assigning the final object to result

3. Zero-Config Deployment

   • No GCP credentials or environment variables needed for end-users
   • All AI calls go through our Cloud Run service under our own service account

4. Local Fallback

   • If the AI service is unreachable, basic read|load … + head|describe still works via regex parsing

5. File Loading

   • Detects .csv, .xls, .xlsx, and .json by extension
   • Returns a pandas.DataFrame

6. Plotting Support

   • Generates histograms, scatter plots, line plots, etc.
   • Returns a matplotlib.axes.Axes for further customization

7. CLI & Packaging Structure

   • cli.py exposes the speak2py shell command
   • src/speak2py/__init__.py provides the speak2py() function

8. Testing & Observability

   • Unit tests for file loading and regex fallback
   • Integration tests for both CLI and Python API
   • Server logs LLM latency, execution time, and errors

---

📦 Installation

pip install speak2py
## MVP v0.3 Description

- **Purpose:**
  Empower anyone to write and execute Python data‐analysis or algorithmic code using plain-English prompts—without installing AI libraries or managing credentials.

- **What’s Included:**
  - `speak2py(command: str) → DataFrame | Axes`
    • Sends your English command to a hosted AI service, executes the returned snippet, and returns the result.
  - **Local Regex Fallback**
    • For simple `read|load … + head|describe` commands when offline.
  - **File Formats**
    • `.csv`, `.xls`/`.xlsx`, `.json` automatically detected and loaded into pandas.
  - **Plotting**
    • Histogram, scatter, line‐plot support via matplotlib, returned as `Axes`.
  - **CLI Tool**
    • `speak2py "..." --show [--out file]` for shell usage.
  - **Zero-Config Deployment**
    • All AI inference happens on our Cloud Run endpoint—no GCP setup on the client side.
  - **Testing & Observability**
    • Unit tests (file loading, fallback) and integration tests (AI client + execution).
    • Server‐side logs of LLM latency, execution time, and errors.

- **Why It Matters:**
  This MVP lays the groundwork for making Python coding accessible—non-developers can load data, visualize it, or even run algorithms (e.g. prime number generation) by simply typing what they want in English.

---

## Next Steps & Roadmap

1. **Extended Plot Types**
   - Boxplots, pivot-tables, pairwise scatter–matrix.

2. **More Data Sources**
   - Parquet, SQL databases, REST APIs, GCS buckets.

3. **Advanced Prompting**
   - Few-shot examples, customizable templates, context retention.

4. **IDE/Notebook Integration**
   - JupyterMagics (e.g. `%%speak2py`), VS Code extension.

5. **User-Defined Macros**
   - Let users define their own English→Python shortcuts.

6. **Security & Sandboxing**
   - Harden execution sandbox, validate generated code before running.

7. **Analytics & Usage Dashboard**
   - Track popular commands, lagging bottlenecks, error trends.

Feel free to pick any roadmap item to contribute or request via issues/pull-requests!

---

## Contributing

Contributions welcome! Please open an issue or submit a pull request.

## License

MIT © 2025 Speak2Py Contributors