speak2py

Name	speak2py JSON
Version	0.2.2 JSON
	download
home_page	None
Summary	MVP: Load CSV/Excel/JSON into a pandas DataFrame via speak2py()
upload_time	2025-07-15 02:55:46
maintainer	None
docs_url	None
author	Varun Pulipati
requires_python	>=3.7
license	None
keywords
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # 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:

```bash
pip install speak2py

```

---

## MVP Features (v0.1)

1. **Natural-Language Commands**

   - **CLI**:
     ```bash
     speak2py "read file 'data.csv' and head 5" --show
     ```
   - **Python API**:
     ```python
     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

```bash
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.

---

## Contributing

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

## License

MIT © 2025 Speak2Py Contributors

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "speak2py",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.7",
    "maintainer_email": null,
    "keywords": null,
    "author": "Varun Pulipati",
    "author_email": null,
    "download_url": "https://files.pythonhosted.org/packages/76/63/3e3a0290cd36ab6534c7b9d2f7a33104e19729f2bb87c2755366bcb51485/speak2py-0.2.2.tar.gz",
    "platform": null,
    "description": "# Speak2Py\r\n\r\n**Version:** MVP v0.1\r\n\r\n---\r\n\r\n## \ud83c\udfaf Objective\r\n\r\nLet users run **any** Python logic\u2014data loading, analysis, plotting, even algorithm, data structures generation\u2014by writing plain-English commands. The MVP proves out:\r\n\r\n- **English\u2192Python translation** via a hosted AI (Gemini on Vertex AI)\r\n- **Safe execution** of the generated code and return of results\r\n- **Zero-config UX**: no local AI models, no credentials, just install and run\r\n\r\n---\r\n\r\n## \ud83d\udcdd Overview\r\n\r\nSpeak2Py accepts natural-language prompts such as:\r\n\r\n- \u201cread file \u2018data.csv\u2019 and head 5\u201d\r\n- \u201cplot x vs y from \u2018data.csv\u2019\u201d\r\n- \u201cgenerate prime numbers up to 100 and assign to result\u201d\r\n\r\nBehind the scenes it:\r\n\r\n1. Sends your prompt to a hosted FastAPI service on Cloud Run\r\n2. Calls Gemini to produce a Python snippet assigning its output to `result`\r\n3. Executes that snippet in a sandboxed namespace\r\n4. Serializes and returns `result` as a DataFrame, list, or plot\r\n\r\nEnd users simply:\r\n\r\n```bash\r\npip install speak2py\r\n\r\n```\r\n\r\n---\r\n\r\n## MVP Features (v0.1)\r\n\r\n1. **Natural-Language Commands**\r\n\r\n   - **CLI**:\r\n     ```bash\r\n     speak2py \"read file 'data.csv' and head 5\" --show\r\n     ```\r\n   - **Python API**:\r\n     ```python\r\n     from speak2py import speak2py\r\n     df = speak2py(\"load 'data.csv' and describe\")\r\n     ```\r\n\r\n2. **AI-Driven Code Generation**\r\n\r\n   - Sends your English prompt to a hosted Gemini/Vertex AI service\r\n   - Automatically generates and executes a Python snippet assigning the final object to `result`\r\n\r\n3. **Zero-Config Deployment**\r\n\r\n   - No GCP credentials or environment variables needed for end-users\r\n   - All AI calls go through our Cloud Run service under our own service account\r\n\r\n4. **Local Fallback**\r\n\r\n   - If the AI service is unreachable, basic `read|load \u2026 + head|describe` still works via regex parsing\r\n\r\n5. **File Loading**\r\n\r\n   - Detects `.csv`, `.xls`, `.xlsx`, and `.json` by extension\r\n   - Returns a `pandas.DataFrame`\r\n\r\n6. **Plotting Support**\r\n\r\n   - Generates histograms, scatter plots, line plots, etc.\r\n   - Returns a `matplotlib.axes.Axes` for further customization\r\n\r\n7. **CLI & Packaging Structure**\r\n\r\n   - `cli.py` exposes the `speak2py` shell command\r\n   - `src/speak2py/__init__.py` provides the `speak2py()` function\r\n\r\n8. **Testing & Observability**\r\n   - **Unit tests** for file loading and regex fallback\r\n   - **Integration tests** for both CLI and Python API\r\n   - Server logs LLM latency, execution time, and errors\r\n\r\n---\r\n\r\n## \ud83d\udce6 Installation\r\n\r\n```bash\r\npip install speak2py\r\n```\r\n\r\n## MVP v0.3 Description\r\n\r\n- **Purpose:**  \r\n  Empower anyone to write and execute Python data\u2010analysis or algorithmic code using plain-English prompts\u2014without installing AI libraries or managing credentials.\r\n\r\n- **What\u2019s Included:**\r\n\r\n  - `speak2py(command: str) \u2192 DataFrame | Axes`  \r\n    Sends your English command to a hosted AI service, executes the returned snippet, and returns the result.\r\n  - **Local Regex Fallback**  \r\n    For simple `read|load \u2026 + head|describe` commands when offline.\r\n  - **File Formats**  \r\n    `.csv`, `.xls`/`.xlsx`, `.json` automatically detected and loaded into pandas.\r\n  - **Plotting**  \r\n    Histogram, scatter, line\u2010plot support via matplotlib, returned as `Axes`.\r\n  - **CLI Tool**  \r\n    `speak2py \"...\" --show [--out file]` for shell usage.\r\n  - **Zero-Config Deployment**  \r\n    All AI inference happens on our Cloud Run endpoint\u2014no GCP setup on the client side.\r\n  - **Testing & Observability**  \r\n    Unit tests (file loading, fallback) and integration tests (AI client + execution).  \r\n    Server\u2010side logs of LLM latency, execution time, and errors.\r\n\r\n- **Why It Matters:**  \r\n  This MVP lays the groundwork for making Python coding accessible\u2014non-developers can load data, visualize it, or even run algorithms (e.g. prime number generation) by simply typing what they want in English.\r\n\r\n---\r\n\r\n## Next Steps & Roadmap\r\n\r\n1. **Extended Plot Types**  \r\n   Boxplots, pivot\u2010tables, pairwise scatter\u2010matrix.\r\n\r\n2. **More Data Sources**  \r\n   Parquet, SQL databases, REST APIs, GCS buckets.\r\n\r\n3. **Advanced Prompting**  \r\n   Few\u2010shot examples, customizable templates, context retention.\r\n\r\n4. **IDE/Notebook Integration**  \r\n   JupyterMagics (e.g. `%%speak2py`), VS Code extension.\r\n\r\n5. **User\u2010Defined Macros**  \r\n   Let users define their own English\u2192Python shortcuts.\r\n\r\n6. **Security & Sandboxing**  \r\n   Harden execution sandbox, validate generated code before running.\r\n\r\n7. **Analytics & Usage Dashboard**  \r\n   Track popular commands, lagging bottlenecks, error trends.\r\n\r\n---\r\n\r\n## Contributing\r\n\r\nContributions welcome! Please open an issue or submit a pull request.\r\n\r\n## License\r\n\r\nMIT \u00a9 2025 Speak2Py Contributors\r\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "MVP: Load CSV/Excel/JSON into a pandas DataFrame via speak2py()",
    "version": "0.2.2",
    "project_urls": null,
    "split_keywords": [],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "56765a3644abaaaa049265c433fc819ca1114aff62351665fe3b1c331cbe5ec1",
                "md5": "32cd5dbaa27f76e0b8c6c8b1cf953cda",
                "sha256": "25879c8e4f0da22782d8d53faec526685976bc3281cee6d1e1454f1f89969630"
            },
            "downloads": -1,
            "filename": "speak2py-0.2.2-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "32cd5dbaa27f76e0b8c6c8b1cf953cda",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.7",
            "size": 7731,
            "upload_time": "2025-07-15T02:55:45",
            "upload_time_iso_8601": "2025-07-15T02:55:45.796681Z",
            "url": "https://files.pythonhosted.org/packages/56/76/5a3644abaaaa049265c433fc819ca1114aff62351665fe3b1c331cbe5ec1/speak2py-0.2.2-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "76633e3a0290cd36ab6534c7b9d2f7a33104e19729f2bb87c2755366bcb51485",
                "md5": "5c5093e7d2756661c90ef86d8e941489",
                "sha256": "91b7d0313b9b4a1bfce554a524b1cbcf7075a515f2ea34c1b28a58f98d7e6683"
            },
            "downloads": -1,
            "filename": "speak2py-0.2.2.tar.gz",
            "has_sig": false,
            "md5_digest": "5c5093e7d2756661c90ef86d8e941489",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7",
            "size": 10369,
            "upload_time": "2025-07-15T02:55:46",
            "upload_time_iso_8601": "2025-07-15T02:55:46.779421Z",
            "url": "https://files.pythonhosted.org/packages/76/63/3e3a0290cd36ab6534c7b9d2f7a33104e19729f2bb87c2755366bcb51485/speak2py-0.2.2.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-15 02:55:46",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "lcname": "speak2py"
}