# psyborg
[](https://github.com/m4xw311/psyborg/actions/workflows/workflow.yml)
[](https://badge.fury.io/py/psyborg)
[](https://pypi.org/project/psyborg/)
[](https://github.com/m4xw311/psyborg/blob/main/LICENSE)
An agentless vibe coding framework for seamlessly mixing code and LLM instructions in executable markdown files. psyborg enables you to write polyglot programs that support both traditional programming languages and natural language instructions, all executed in a shared runtime environment.
## Overview
psyborg lets you write markdown files that mix Python code with natural language instructions. The code blocks execute normally, while text between them becomes prompts for an LLM to generate and execute additional code - all in the same runtime environment with shared variables.
## Features
- **Seamless Integration**: Mix Python code and natural language instructions in markdown files
- **Shared Runtime**: All code blocks and LLM-generated code share the same execution context
- **State Preservation**: Variables and their values persist across code blocks and LLM instructions
- **Simple Syntax**: Use standard markdown code blocks and plain text instructions
- **Flexible LLM Backend**: Supports OpenAI-compatible APIs (including local models)
- **Easy Installation**: Available as a pip-installable package with CLI support
- **Code Export**: Generate standalone Python scripts from your psyborg executions for reuse
- **Smart Caching**: Automatic caching of code execution results and LLM responses for faster iterative development
## Installation
### From PyPI (Recommended)
```bash
pip install psyborg
```
### From Source (Development)
```bash
git clone https://github.com/m4xw311/psyborg.git
cd psyborg
pip install -e .
```
For development with additional tools:
```bash
pip install -e ".[dev]"
```
## Configuration
Create a `.env` file in your project directory with your OpenAI API configuration:
```env
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_BASE_URL=https://api.openai.com/v1 # Optional: for custom endpoints
OPENAI_MODEL=gpt-4 # Optional: defaults to gpt-4
```
Alternatively, you can set these as environment variables:
```bash
export OPENAI_API_KEY="your_openai_api_key_here"
export OPENAI_BASE_URL="https://api.openai.com/v1" # Optional
export OPENAI_MODEL="gpt-4" # Optional
```
## Quick Start
1. **Create a markdown file** (e.g., `hello.md`):
```markdown
# My First psyborg Script
```python
name = "World"
print(f"Hello, {name}!")
```
Now create a greeting function that takes a name parameter and returns a personalized greeting.
```python
print(greeting("psyborg"))
```
```
2. **Run it with psyborg**:
```bash
psyborg hello.md
```
The output will show:
- "Hello, World!" from the first code block
- The LLM will generate a `greeting()` function based on your instruction
- "Hello, psyborg!" from calling the generated function
## How It Works
psyborg processes your markdown file sequentially:
1. **Code blocks** (```python) are executed directly in the Python interpreter
2. **Text sections** between code blocks are sent to the LLM as prompts to generate new code
3. **Generated code** is executed in the same runtime environment
4. **Variables and functions** persist across all code blocks and LLM generations
5. **Results** are displayed in real-time as execution progresses
## Command Line Options
```bash
psyborg [options] <markdown_file>
Options:
-h, --help Show help message
-v, --verbose Enable verbose output for debugging
--version Show version information
--clear-cache Clear execution cache before running
--export FILE Export executed code to a Python file
--dry-run Parse and validate without executing
```
### Examples
```bash
# Basic execution
psyborg script.md
# Export the executed code to a Python file
psyborg script.md --export output.py
# Clear cache and run with verbose output
psyborg script.md --clear-cache --verbose
# Validate syntax without executing
psyborg script.md --dry-run
```
## Advanced Usage
### Working with Variables
Variables defined in code blocks are available to subsequent LLM instructions:
```markdown
```python
data = [1, 2, 3, 4, 5]
```
Create a function to calculate the average of the data list.
```python
print(f"Average: {calculate_average(data)}")
```
```
### Multiple Instructions
You can have multiple instruction sections that build upon each other:
```markdown
```python
import pandas as pd
df = pd.DataFrame({'x': [1, 2, 3], 'y': [4, 5, 6]})
```
Add a new column 'z' that is the sum of columns 'x' and 'y'.
Now create a visualization of all three columns using matplotlib.
```python
print("Final DataFrame:")
print(df)
```
```
### Custom LLM Endpoints
psyborg supports any OpenAI-compatible API endpoint:
```bash
# For local models (e.g., Ollama, LocalAI)
export OPENAI_BASE_URL="http://localhost:11434/v1"
export OPENAI_API_KEY="not-needed"
export OPENAI_MODEL="llama2"
# For other providers
export OPENAI_BASE_URL="https://your-provider.com/v1"
export OPENAI_API_KEY="your-key"
export OPENAI_MODEL="your-model"
```
## Caching
psyborg automatically caches:
- Code execution results
- LLM responses for identical prompts
- Variable states between runs
Cache is stored in `.psyborg_cache/` and persists across sessions. Use `--clear-cache` to reset.
## Code Export
Generate standalone Python scripts from your psyborg executions:
```bash
psyborg script.md --export generated_script.py
```
The exported file includes:
- All original code blocks
- LLM-generated code with comments indicating their source
- Proper imports and structure for standalone execution
## Best Practices
1. **Start Simple**: Begin with basic Python code blocks and simple instructions
2. **Be Specific**: Clear, specific instructions yield better LLM-generated code
3. **Iterative Development**: Use psyborg's caching for fast iteration cycles
4. **Variable Context**: Remember that the LLM can see and use all previously defined variables
5. **Export for Production**: Use `--export` to create deployable Python scripts
## Examples
Check the `examples/` directory for sample psyborg scripts demonstrating various use cases:
- Data analysis and visualization
- Web scraping and API integration
- Machine learning workflows
- File processing and automation
- Mathematical computations
## Troubleshooting
### Common Issues
**"OpenAI API key not found"**
- Set `OPENAI_API_KEY` in your environment or `.env` file
**"Module not found" errors**
- Install required Python packages: `pip install package-name`
**Cache-related issues**
- Clear cache with: `psyborg script.md --clear-cache`
**LLM generates incorrect code**
- Be more specific in your instructions
- Provide examples of expected input/output
- Break complex tasks into smaller steps
### Debug Mode
Use verbose mode to see detailed execution information:
```bash
psyborg script.md --verbose
```
This shows:
- Cache hit/miss information
- LLM prompts and responses
- Code execution details
- Variable state changes
## Contributing
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
### Development Setup
```bash
git clone https://github.com/m4xw311/psyborg.git
cd psyborg
pip install -e ".[dev]"
```
### Running Tests
```bash
pytest
pytest --cov=psyborg # With coverage report
```
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for version history and release notes.
---
**psyborg** - Where code meets natural language in perfect harmony. 🤖✨
Raw data
{
"_id": null,
"home_page": "https://github.com/m4xw311/psyborg",
"name": "psyborg",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "llm, ai, markdown, code-execution, polyglot, scripting",
"author": "Maxwell Felix",
"author_email": "max@alloai.io",
"download_url": "https://files.pythonhosted.org/packages/13/f0/fe84c3ae0a97cfecf572583c1c9a087118f196821d7e7921e879f032a4ba/psyborg-0.4.0.tar.gz",
"platform": null,
"description": "# psyborg\n\n[](https://github.com/m4xw311/psyborg/actions/workflows/workflow.yml)\n[](https://badge.fury.io/py/psyborg)\n[](https://pypi.org/project/psyborg/)\n[](https://github.com/m4xw311/psyborg/blob/main/LICENSE)\n\nAn agentless vibe coding framework for seamlessly mixing code and LLM instructions in executable markdown files. psyborg enables you to write polyglot programs that support both traditional programming languages and natural language instructions, all executed in a shared runtime environment.\n\n## Overview\n\npsyborg lets you write markdown files that mix Python code with natural language instructions. The code blocks execute normally, while text between them becomes prompts for an LLM to generate and execute additional code - all in the same runtime environment with shared variables.\n\n## Features\n\n- **Seamless Integration**: Mix Python code and natural language instructions in markdown files\n- **Shared Runtime**: All code blocks and LLM-generated code share the same execution context\n- **State Preservation**: Variables and their values persist across code blocks and LLM instructions\n- **Simple Syntax**: Use standard markdown code blocks and plain text instructions\n- **Flexible LLM Backend**: Supports OpenAI-compatible APIs (including local models)\n- **Easy Installation**: Available as a pip-installable package with CLI support\n- **Code Export**: Generate standalone Python scripts from your psyborg executions for reuse\n- **Smart Caching**: Automatic caching of code execution results and LLM responses for faster iterative development\n\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\npip install psyborg\n```\n\n### From Source (Development)\n\n```bash\ngit clone https://github.com/m4xw311/psyborg.git\ncd psyborg\npip install -e .\n```\n\nFor development with additional tools:\n```bash\npip install -e \".[dev]\"\n```\n\n## Configuration\n\nCreate a `.env` file in your project directory with your OpenAI API configuration:\n\n```env\nOPENAI_API_KEY=your_openai_api_key_here\nOPENAI_BASE_URL=https://api.openai.com/v1 # Optional: for custom endpoints\nOPENAI_MODEL=gpt-4 # Optional: defaults to gpt-4\n```\n\nAlternatively, you can set these as environment variables:\n\n```bash\nexport OPENAI_API_KEY=\"your_openai_api_key_here\"\nexport OPENAI_BASE_URL=\"https://api.openai.com/v1\" # Optional\nexport OPENAI_MODEL=\"gpt-4\" # Optional\n```\n\n## Quick Start\n\n1. **Create a markdown file** (e.g., `hello.md`):\n\n```markdown\n# My First psyborg Script\n\n```python\nname = \"World\"\nprint(f\"Hello, {name}!\")\n```\n\nNow create a greeting function that takes a name parameter and returns a personalized greeting.\n\n```python\nprint(greeting(\"psyborg\"))\n```\n```\n\n2. **Run it with psyborg**:\n\n```bash\npsyborg hello.md\n```\n\nThe output will show:\n- \"Hello, World!\" from the first code block\n- The LLM will generate a `greeting()` function based on your instruction\n- \"Hello, psyborg!\" from calling the generated function\n\n## How It Works\n\npsyborg processes your markdown file sequentially:\n\n1. **Code blocks** (```python) are executed directly in the Python interpreter\n2. **Text sections** between code blocks are sent to the LLM as prompts to generate new code\n3. **Generated code** is executed in the same runtime environment\n4. **Variables and functions** persist across all code blocks and LLM generations\n5. **Results** are displayed in real-time as execution progresses\n\n## Command Line Options\n\n```bash\npsyborg [options] <markdown_file>\n\nOptions:\n -h, --help Show help message\n -v, --verbose Enable verbose output for debugging\n --version Show version information\n --clear-cache Clear execution cache before running\n --export FILE Export executed code to a Python file\n --dry-run Parse and validate without executing\n```\n\n### Examples\n\n```bash\n# Basic execution\npsyborg script.md\n\n# Export the executed code to a Python file\npsyborg script.md --export output.py\n\n# Clear cache and run with verbose output\npsyborg script.md --clear-cache --verbose\n\n# Validate syntax without executing\npsyborg script.md --dry-run\n```\n\n## Advanced Usage\n\n### Working with Variables\n\nVariables defined in code blocks are available to subsequent LLM instructions:\n\n```markdown\n```python\ndata = [1, 2, 3, 4, 5]\n```\n\nCreate a function to calculate the average of the data list.\n\n```python\nprint(f\"Average: {calculate_average(data)}\")\n```\n```\n\n### Multiple Instructions\n\nYou can have multiple instruction sections that build upon each other:\n\n```markdown\n```python\nimport pandas as pd\ndf = pd.DataFrame({'x': [1, 2, 3], 'y': [4, 5, 6]})\n```\n\nAdd a new column 'z' that is the sum of columns 'x' and 'y'.\n\nNow create a visualization of all three columns using matplotlib.\n\n```python\nprint(\"Final DataFrame:\")\nprint(df)\n```\n```\n\n### Custom LLM Endpoints\n\npsyborg supports any OpenAI-compatible API endpoint:\n\n```bash\n# For local models (e.g., Ollama, LocalAI)\nexport OPENAI_BASE_URL=\"http://localhost:11434/v1\"\nexport OPENAI_API_KEY=\"not-needed\"\nexport OPENAI_MODEL=\"llama2\"\n\n# For other providers\nexport OPENAI_BASE_URL=\"https://your-provider.com/v1\"\nexport OPENAI_API_KEY=\"your-key\"\nexport OPENAI_MODEL=\"your-model\"\n```\n\n## Caching\n\npsyborg automatically caches:\n- Code execution results\n- LLM responses for identical prompts\n- Variable states between runs\n\nCache is stored in `.psyborg_cache/` and persists across sessions. Use `--clear-cache` to reset.\n\n## Code Export\n\nGenerate standalone Python scripts from your psyborg executions:\n\n```bash\npsyborg script.md --export generated_script.py\n```\n\nThe exported file includes:\n- All original code blocks\n- LLM-generated code with comments indicating their source\n- Proper imports and structure for standalone execution\n\n## Best Practices\n\n1. **Start Simple**: Begin with basic Python code blocks and simple instructions\n2. **Be Specific**: Clear, specific instructions yield better LLM-generated code\n3. **Iterative Development**: Use psyborg's caching for fast iteration cycles\n4. **Variable Context**: Remember that the LLM can see and use all previously defined variables\n5. **Export for Production**: Use `--export` to create deployable Python scripts\n\n## Examples\n\nCheck the `examples/` directory for sample psyborg scripts demonstrating various use cases:\n\n- Data analysis and visualization\n- Web scraping and API integration\n- Machine learning workflows\n- File processing and automation\n- Mathematical computations\n\n## Troubleshooting\n\n### Common Issues\n\n**\"OpenAI API key not found\"**\n- Set `OPENAI_API_KEY` in your environment or `.env` file\n\n**\"Module not found\" errors**\n- Install required Python packages: `pip install package-name`\n\n**Cache-related issues**\n- Clear cache with: `psyborg script.md --clear-cache`\n\n**LLM generates incorrect code**\n- Be more specific in your instructions\n- Provide examples of expected input/output\n- Break complex tasks into smaller steps\n\n### Debug Mode\n\nUse verbose mode to see detailed execution information:\n\n```bash\npsyborg script.md --verbose\n```\n\nThis shows:\n- Cache hit/miss information\n- LLM prompts and responses\n- Code execution details\n- Variable state changes\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Development Setup\n\n```bash\ngit clone https://github.com/m4xw311/psyborg.git\ncd psyborg\npip install -e \".[dev]\"\n```\n\n### Running Tests\n\n```bash\npytest\npytest --cov=psyborg # With coverage report\n```\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for version history and release notes.\n\n---\n\n**psyborg** - Where code meets natural language in perfect harmony. \ud83e\udd16\u2728\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Write markdown files mixing Python code with natural language prompts that generate and execute additional code in a shared runtime",
"version": "0.4.0",
"project_urls": {
"Bug Tracker": "https://github.com/m4xw311/psyborg/issues",
"Documentation": "https://github.com/m4xw311/psyborg#readme",
"Homepage": "https://github.com/m4xw311/psyborg",
"Repository": "https://github.com/m4xw311/psyborg.git"
},
"split_keywords": [
"llm",
" ai",
" markdown",
" code-execution",
" polyglot",
" scripting"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "81c6becdecce2c7905bb06edd3ceea2bb16ee447e7431fb737a6eec87efe50f6",
"md5": "a9857e8ea1eb2ea9d2a57364fd0b7746",
"sha256": "b28e41133387bdcf3c9d083a1c3770f9ff518700919d1ca2b9bb00064a1bc274"
},
"downloads": -1,
"filename": "psyborg-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a9857e8ea1eb2ea9d2a57364fd0b7746",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 14783,
"upload_time": "2025-09-03T03:08:57",
"upload_time_iso_8601": "2025-09-03T03:08:57.840939Z",
"url": "https://files.pythonhosted.org/packages/81/c6/becdecce2c7905bb06edd3ceea2bb16ee447e7431fb737a6eec87efe50f6/psyborg-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "13f0fe84c3ae0a97cfecf572583c1c9a087118f196821d7e7921e879f032a4ba",
"md5": "1fc19eb08a341fad77517f2d147ade06",
"sha256": "fce4f6055c3bf4ce3181cc0384d32cf38a99cb993024784139789a910ae92b46"
},
"downloads": -1,
"filename": "psyborg-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "1fc19eb08a341fad77517f2d147ade06",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 19845,
"upload_time": "2025-09-03T03:08:59",
"upload_time_iso_8601": "2025-09-03T03:08:59.087075Z",
"url": "https://files.pythonhosted.org/packages/13/f0/fe84c3ae0a97cfecf572583c1c9a087118f196821d7e7921e879f032a4ba/psyborg-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-03 03:08:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "m4xw311",
"github_project": "psyborg",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "openai",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"0.19.0"
]
]
},
{
"name": "cloudpickle",
"specs": [
[
">=",
"3.1.1"
]
]
}
],
"lcname": "psyborg"
}
JSON
