Pytinel

Pytinel (Python Terminal in Natural Executable Language) is an augmented interactive terminal utility that emulates the interface of the standard Python REPL. It transcends the conventional Python interactive experience by empowering users to articulate intended operations through natural language—whereupon Pytinel autonomously generates the requisite Python code and executes it with fluidity.

✨ Key Features

1. Natural Language to Python Execution Describe your desired operation in plain natural language, and Pytinel will silently generate and execute the corresponding Python code, returning only the final result.

   >>> Calculate the sum of numbers from 1 to 100 and output the result
   5050
   
   >>> Compute the area of a circle with a radius of 5 (use pi = 3.14159)
   78.53975
   
   >>> Generate a list of even numbers between 20 and 40 (inclusive)
   [20, 22, 24, 26, 28, 30, 32, 34, 36, 38, 40]
   
   >>> Convert the string "Hello World" to all uppercase letters
   'HELLO WORLD'
   
   >>> Calculate the factorial of 7
   5040
   

2. Safe Execution Model

   • Generated code runs silently in the background by default, with no intermediate code exposure.
   • High-risk operation protection: Operations involving file system modifications, network requests, subprocess invocations, and environment variable alterations require explicit user authorization before execution. When triggering such operations, you will receive a prompt like:

     >>> Create a new text file named "demo.txt" and write the sentence "Hello Pytinel" into it
     Are you sure you want to create and write to file "demo.txt"? (Y/N):
     

     Only input Y/y will proceed with the operation; N/n will abort the execution immediately.

3. Secure Local Credential Management

   • Configuration of an LLM API Key is required to enable natural language parsing capabilities (a guided setup wizard will launch on first run).
   • API credentials are stored locally using platform-adaptive key derivation and AES-based encryption at rest for maximum security.
   • Zero off-device data transmission: No credentials, prompts, generated code, or execution results are sent to external servers. Pytinel collects no telemetry, logs no session data, and performs no external communication.

4. In-process Python REPL Integration Runs as an intelligent in-process REPL, executing code directly within your local runtime environment for consistent and reliable results.

📌 Project Status

This is a toy/experimental project created for learning and fun purposes. It is not intended for production environments or critical workloads.

⚠️ Disclaimer & Security Notice

Disclaimer

This project bears no affiliation with, association to, authorization from, endorsement by, nor any official connection whatsoever to the Python Software Foundation (PSF). All issues, defects, or feature inquiries pertaining to Pytinel should be directed exclusively to this repository’s issue tracker, and not to the PSF.

Security Notice

• Code generated by large language models may harbor logical inconsistencies, security flaws, or unforeseen ramifications.
• While Pytinel incorporates prompt-level risk mitigation measures, it does not conduct static or dynamic analysis of the resultant code.
• By utilizing this tool, you assume full liability for ensuring the safety, accuracy of execution instructions and all attendant consequences.
• Configuration of an LLM API Key is imperative for core functionality—kindly maintain the confidentiality of your API Key and refrain from disclosing it within public repositories or communication platforms.

📦 Installation

Option 1: Install from PyPI via pipx (Recommended for macOS/Linux)

pipx isolates the package and its dependencies, avoiding conflicts with your global or project-specific Python environments—ideal for command-line tools like Pytinel.

# First, install pipx if you haven't already
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# Then install Pytinel via pipx
pipx install pytinel

Option 2: Install from PyPI via pip (Cross-platform)

The classic cross-platform installation method using pip, suitable for all supported Python environments:

pip install pytinel
# For Python 3.x specifically (if needed)
python3 -m pip install pytinel

Option 3: Install from binary (For Windows)

A convenient installation method for Windows users via the official MSI installer — no manual Python environment configuration is required.

System Requirements: This software and its MSI installer are only compatible with Windows 10 and later (64-bit).

1. Download the MSI installer Visit the official pytinel release page: https://github.com/miller-owo/pytinel/releases Download the latest 64-bit Windows MSI installer (file name pattern: pytinel-<version>-windows-<architecture>.msi).

2. Run the installer Double-click the downloaded MSI file to launch the setup wizard:

   • Follow the on-screen prompts (click Next to proceed).
   • The default installation path is C:\Users\[Your Username]\AppData\Local\Programs\pytinel\ (a user-level directory that requires no administrative privileges; custom paths are also supported).
   • Click Install and wait for the process to complete, then click Finish.

   Note: The installer automatically adds the installation directory to your user PATH environment variable — no manual configuration or checkboxes are needed.

3. Verify the installation Close any open Command Prompt (CMD) or PowerShell windows, then open a new terminal window and run:

   pytinel
   

   A successful installation will display pytinel's main interface, help information, or startup prompt (instead of a "command not found" error).

Troubleshooting

If the pytinel command remains unrecognized:

1. Verify that you are utilizing a freshly launched terminal window (pre-existing sessions may fail to register updated PATH configurations).
2. Reboot your system to compel a PATH refresh, thereby resolving the majority of delayed PATH propagation issues.
3. Ascertain that the installation directory is included in your user-specific PATH:
   • Press Win + R, input sysdm.cpl, and press Enter.
   • Navigate to the Advanced tab → Environment Variables.
   • Within User variables, inspect whether the pytinel installation directory is enumerated within the Path variable.
4. Should it be absent, manually append the installation directory to the user Path variable and restart your terminal or computer.

Option 4: Install from Source (For Development/Contribution)

If you want to modify the code or use the latest unreleased version, install in editable mode from the source repository:

# Clone the repository
git clone https://github.com/miller-owo/pytinel.git

# Navigate to project directory
cd pytinel

# Install project dependencies from requirements.txt (required step)
pip install -r requirements.txt

# Install in editable mode (changes to code take effect immediately)
pip install -e .

🔧 Build (Build from Source)

To build distributable packages (wheel/SDist) of Pytinel from the source code (e.g., for PyPI publishing or sharing), follow these steps (aligned with your project directory):

Prerequisites (Build Dependencies)

First, install the tools required for building Python packages, and ensure project dependencies are set up:

# Upgrade pip (recommended)
python3 -m pip install --upgrade pip

# Install build tools (required for packaging)
python3 -m pip install build setuptools wheel

# Install Pytinel's project dependencies (from requirements.txt in the root directory)
pip install -r requirements.txt

Build the Package

From the project root directory (the folder containing main.py, pt_config.py, etc.), run:

# Run the build command (automatically detects project files)
python3 -m build

Build Output

After a successful build, two package types will be generated in the dist/ directory (created automatically):

Note: Replace <version> with your project's actual version number (e.g., 0.1.0) in the filenames below.

1. Wheel package (pytinel-<version>-py3-none-any.whl): A pre-built, fast-installable package.
2. Source distribution (SDist) (pytinel-<version>.tar.gz): A compressed source code archive (required for PyPI publishing).

Install from the Built Package

Test the locally built package with pip:

pip install dist/pytinel-<version>-py3-none-any.whl

🚀 Getting Started

1. First Run: Guided LLM Configuration Wizard

When you launch Pytinel for the first time, a step-by-step interactive setup wizard will automatically launch to help you configure your LLM credentials. No manual pre-configuration is required—follow the on-screen prompts to complete the setup:

1. Select LLM Provider: Currently, only OpenAI-compatible APIs are supported.
2. Specify Model Name: Enter the desired OpenAI model name (e.g., gpt-4o).
3. Input API Key: Provide your valid OpenAI API Key when prompted.
4. Secure Storage: Your API Key will be immediately encrypted using AES encryption (with platform-adaptive key derivation) and stored locally on your device—never transmitted externally.

2. Launch Pytinel

After installation, launch Pytinel directly from the terminal with a single command:

pytinel

3. Basic Usage

Once the initial configuration is complete, you can start using Pytinel immediately. Enter natural language prompts directly after the >>> prompt to get results:

>>> Calculate the result of 3 squared plus 5 cubed
134
>>> Print the current date in YYYY-MM-DD format
2026-01-18

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.