| Name | xoptpy JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | eXtreme OPTimization - More optimizing agentic AI |
| upload_time | 2025-08-01 13:27:31 |
| maintainer | None |
| docs_url | None |
| author | Jake Derry |
| requires_python | <3.14,>=3.9 |
| license | None |
| keywords |
optimization
ai
agentic
llm
agents
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# xopt - eXtreme OPTimization
More optimizing agentic AI with modular, isolated execution environments.
## Overview
xopt is a modular AI framework that allows you to package, distribute, and run AI modules in isolated virtual environments. Each module can have its own dependencies, configurations, and tunables - perfect for optimization workflows where parameters need to be adjusted between runs.
## Key Features
- **Isolated Execution**: Each module runs in its own virtual environment
- **Lightweight Packaging**: Modules packaged as `.xopt` archives (~5-20MB vs 100-500MB containers)
- **Persistent Configuration**: Tunables and configurables survive between runs
- **Project-Based Dependencies**: Declare dependencies once, run many times
- **Optimization-Friendly**: Modify parameters without reinstalling modules
## Installation
```bash
git clone <repository>
cd xoptpy
poetry install
```
## Quick Start
### 1. Install Example Modules
```bash
# Package the React reasoning module
python3 -m xopt package examples/modules/react
# Package the Calculator module
python3 -m xopt package examples/modules/calculator
# Install both modules
python3 -m xopt install xopt_react-0.1.0.xopt
python3 -m xopt install xopt_calculator-0.1.0.xopt
```
### 2. Run Modules
```bash
# Run calculator module
python3 -m xopt run "xopt/calculator" "sqrt(16) + 2 * pi"
# Run React reasoning module
python3 -m xopt run "xopt/react" "What is the area of a circle with radius 5?"
```
## CLI Commands
### Module Management
#### `xopt package <module_dir>`
Package a module directory into a `.xopt` archive.
```bash
python3 -m xopt package examples/modules/react
python3 -m xopt package examples/modules/calculator -o my-calc.xopt
```
#### `xopt install <package.xopt>`
Install a module package with isolated virtual environment.
```bash
python3 -m xopt install xopt_react-0.1.0.xopt
```
#### `xopt uninstall <module_name>`
Remove an installed module.
```bash
python3 -m xopt uninstall "xopt/react"
```
#### `xopt list`
List all installed modules.
```bash
python3 -m xopt list
# Output:
# Installed modules:
# xopt/react@0.1.0 - /home/user/.xopt/modules/xopt_react
# xopt/calculator@0.1.0 - /home/user/.xopt/modules/xopt_calculator
```
### Running Modules
#### `xopt run <module> "<input>"`
Run an installed module with input.
```bash
python3 -m xopt run "xopt/calculator" "2 + 2"
python3 -m xopt run "xopt/react" "What is 5 times 7?"
# With config overrides
python3 -m xopt run "xopt/react" "Hello" -c '{"tunables": {"react_prompt": "Be very concise"}}'
```
#### `xopt dev <module_dir> <module> "<input>"`
Run a module directly from development directory (no installation required).
```bash
python3 -m xopt dev examples/modules/react "xopt/react" "What is 2+2?"
```
### Project-Based Workflow
#### `xopt init`
Initialize a new xopt project with dependency management.
```bash
python3 -m xopt init
```
Creates:
```
.xopt/
deps.toml # Dependency declarations
```
#### `xopt sync`
Install all project dependencies declared in `.xopt/deps.toml`.
```bash
python3 -m xopt sync
```
#### `xopt prun <module> "<input>"`
Run module using project-specific configuration.
```bash
python3 -m xopt prun "xopt/react" "What is the square root of 144?"
```
## Project Structure
### Basic Project Setup
```bash
# 1. Initialize project
python3 -m xopt init
# 2. Edit dependencies
cat > .xopt/deps.toml << EOF
[modules]
"xopt/react" = "0.1.0"
"xopt/calculator" = "0.1.0"
[sources]
"xopt/react" = { path = "examples/modules/react" }
"xopt/calculator" = { path = "examples/modules/calculator" }
EOF
# 3. Create module configurations
cat > .xopt/xopt-react.toml << EOF
[tunables]
react_prompt = "You are a helpful math tutor. Show your work step by step."
[configurables]
tool_list = ["xopt/calculator:0.1.0"]
EOF
# 4. Install dependencies
python3 -m xopt sync
# 5. Run with project config
python3 -m xopt prun "xopt/react" "Calculate 15% of 240"
```
### Configuration Files
#### `.xopt/deps.toml` - Dependency Declaration
```toml
[modules]
"xopt/react" = "0.1.0"
"xopt/calculator" = "0.1.0"
# For development - reference local source
[sources]
"xopt/react" = { path = "examples/modules/react" }
"xopt/calculator" = { path = "examples/modules/calculator" }
# Future: Module registries
[registries]
default = "https://registry.xopt.ai"
```
#### `.xopt/xopt-<module>.toml` - Module Configuration
```toml
# .xopt/xopt-react.toml
[tunables]
react_prompt = """Custom prompt for this project..."""
[configurables]
tool_list = ["xopt/calculator:0.1.0", "xopt/websearch:1.0.0"]
```
## Module Development
### Creating a Module
1. **Create module directory**:
```bash
mkdir my-module
cd my-module
```
2. **Add module metadata** (`xopt.yaml`):
```yaml
my-org/my-module@1.0.0:
configurables:
some_list: []
tunables:
some_param: "default value"
```
3. **Add dependencies** (`pyproject.toml`):
```toml
[project]
name = "my-module"
version = "1.0.0"
dependencies = [
"xopt @ file:///path/to/xoptpy"
]
```
4. **Implement module** (`my_module.py`):
```python
import xopt
from xopt.models import Module, StepResult
@xopt.module
def my_module() -> Module:
module = Module(
name="my-org/my-module",
version="1.0.0",
description="My custom module"
)
@xopt.step
def process(input_data: str) -> StepResult:
# Your module logic here
return StepResult(
action="response",
content=f"Processed: {input_data}"
)
module.register("process", process, str)
module.set_start_step("process")
return module
xopt.register(my_module)
```
5. **Package and install**:
```bash
python3 -m xopt package .
python3 -m xopt install my-org_my-module-1.0.0.xopt
```
## Examples
### Math Calculation Chain
```bash
python3 -m xopt run "xopt/react" "First calculate 12 * 15, then find the square root of that result"
```
### Custom Configuration
```bash
# Create custom React configuration
cat > .xopt/xopt-react.toml << EOF
[tunables]
react_prompt = "You are a precise mathematician. Always show detailed calculations."
[configurables]
tool_list = ["xopt/calculator:0.1.0"]
EOF
# Run with custom config
python3 -m xopt prun "xopt/react" "What is 25% of 480?"
```
### Optimization Workflow
```python
# optimization.py - Example parameter tuning
import subprocess
import json
prompts = [
"Be concise and direct.",
"Show detailed step-by-step reasoning.",
"Focus on accuracy over speed."
]
for i, prompt in enumerate(prompts):
config = {"tunables": {"react_prompt": f"You are helpful. {prompt}"}}
result = subprocess.run([
"python3", "-m", "xopt", "run", "xopt/react",
"Calculate the area of a circle with radius 7",
"-c", json.dumps(config)
], capture_output=True, text=True)
print(f"Config {i+1}: {result.stdout}")
```
## Architecture
- **Virtual Environment Isolation**: Each module gets its own Python environment (~/.xopt/modules/)
- **Process-Level Execution**: Modules run in separate processes for crash safety
- **Persistent Configuration**: Tunables stored in module directories survive restarts
- **Dependency Management**: Poetry-style dependency resolution with .xopt/deps.toml
- **Trace Generation**: Automatic execution tracing for debugging and optimization
## Development
```bash
# Install in development mode
poetry install
# Run tests
poetry run pytest
# Package for distribution
poetry build
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request
## License
MIT License - see LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "xoptpy",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.9",
"maintainer_email": null,
"keywords": "optimization, ai, agentic, llm, agents",
"author": "Jake Derry",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/91/42/59a7895b988980e1fa57d12610ad6d7597f1e1679d6087aba059315193a9/xoptpy-0.1.1.tar.gz",
"platform": null,
"description": "# xopt - eXtreme OPTimization\n\nMore optimizing agentic AI with modular, isolated execution environments.\n\n## Overview\n\nxopt is a modular AI framework that allows you to package, distribute, and run AI modules in isolated virtual environments. Each module can have its own dependencies, configurations, and tunables - perfect for optimization workflows where parameters need to be adjusted between runs.\n\n## Key Features\n\n- **Isolated Execution**: Each module runs in its own virtual environment\n- **Lightweight Packaging**: Modules packaged as `.xopt` archives (~5-20MB vs 100-500MB containers) \n- **Persistent Configuration**: Tunables and configurables survive between runs\n- **Project-Based Dependencies**: Declare dependencies once, run many times\n- **Optimization-Friendly**: Modify parameters without reinstalling modules\n\n## Installation\n\n```bash\ngit clone <repository>\ncd xoptpy\npoetry install\n```\n\n## Quick Start\n\n### 1. Install Example Modules\n\n```bash\n# Package the React reasoning module\npython3 -m xopt package examples/modules/react\n\n# Package the Calculator module \npython3 -m xopt package examples/modules/calculator\n\n# Install both modules\npython3 -m xopt install xopt_react-0.1.0.xopt\npython3 -m xopt install xopt_calculator-0.1.0.xopt\n```\n\n### 2. Run Modules\n\n```bash\n# Run calculator module\npython3 -m xopt run \"xopt/calculator\" \"sqrt(16) + 2 * pi\"\n\n# Run React reasoning module\npython3 -m xopt run \"xopt/react\" \"What is the area of a circle with radius 5?\"\n```\n\n## CLI Commands\n\n### Module Management\n\n#### `xopt package <module_dir>`\nPackage a module directory into a `.xopt` archive.\n\n```bash\npython3 -m xopt package examples/modules/react\npython3 -m xopt package examples/modules/calculator -o my-calc.xopt\n```\n\n#### `xopt install <package.xopt>`\nInstall a module package with isolated virtual environment.\n\n```bash\npython3 -m xopt install xopt_react-0.1.0.xopt\n```\n\n#### `xopt uninstall <module_name>`\nRemove an installed module.\n\n```bash\npython3 -m xopt uninstall \"xopt/react\"\n```\n\n#### `xopt list`\nList all installed modules.\n\n```bash\npython3 -m xopt list\n# Output:\n# Installed modules:\n# xopt/react@0.1.0 - /home/user/.xopt/modules/xopt_react\n# xopt/calculator@0.1.0 - /home/user/.xopt/modules/xopt_calculator\n```\n\n### Running Modules\n\n#### `xopt run <module> \"<input>\"`\nRun an installed module with input.\n\n```bash\npython3 -m xopt run \"xopt/calculator\" \"2 + 2\"\npython3 -m xopt run \"xopt/react\" \"What is 5 times 7?\"\n\n# With config overrides\npython3 -m xopt run \"xopt/react\" \"Hello\" -c '{\"tunables\": {\"react_prompt\": \"Be very concise\"}}'\n```\n\n#### `xopt dev <module_dir> <module> \"<input>\"`\nRun a module directly from development directory (no installation required).\n\n```bash\npython3 -m xopt dev examples/modules/react \"xopt/react\" \"What is 2+2?\"\n```\n\n### Project-Based Workflow\n\n#### `xopt init`\nInitialize a new xopt project with dependency management.\n\n```bash\npython3 -m xopt init\n```\n\nCreates:\n```\n.xopt/\n deps.toml # Dependency declarations\n```\n\n#### `xopt sync`\nInstall all project dependencies declared in `.xopt/deps.toml`.\n\n```bash\npython3 -m xopt sync\n```\n\n#### `xopt prun <module> \"<input>\"`\nRun module using project-specific configuration.\n\n```bash\npython3 -m xopt prun \"xopt/react\" \"What is the square root of 144?\"\n```\n\n## Project Structure\n\n### Basic Project Setup\n\n```bash\n# 1. Initialize project\npython3 -m xopt init\n\n# 2. Edit dependencies\ncat > .xopt/deps.toml << EOF\n[modules]\n\"xopt/react\" = \"0.1.0\"\n\"xopt/calculator\" = \"0.1.0\"\n\n[sources]\n\"xopt/react\" = { path = \"examples/modules/react\" }\n\"xopt/calculator\" = { path = \"examples/modules/calculator\" }\nEOF\n\n# 3. Create module configurations\ncat > .xopt/xopt-react.toml << EOF\n[tunables]\nreact_prompt = \"You are a helpful math tutor. Show your work step by step.\"\n\n[configurables]\ntool_list = [\"xopt/calculator:0.1.0\"]\nEOF\n\n# 4. Install dependencies\npython3 -m xopt sync\n\n# 5. Run with project config\npython3 -m xopt prun \"xopt/react\" \"Calculate 15% of 240\"\n```\n\n### Configuration Files\n\n#### `.xopt/deps.toml` - Dependency Declaration\n```toml\n[modules]\n\"xopt/react\" = \"0.1.0\"\n\"xopt/calculator\" = \"0.1.0\"\n\n# For development - reference local source\n[sources]\n\"xopt/react\" = { path = \"examples/modules/react\" }\n\"xopt/calculator\" = { path = \"examples/modules/calculator\" }\n\n# Future: Module registries\n[registries]\ndefault = \"https://registry.xopt.ai\"\n```\n\n#### `.xopt/xopt-<module>.toml` - Module Configuration\n```toml\n# .xopt/xopt-react.toml\n[tunables]\nreact_prompt = \"\"\"Custom prompt for this project...\"\"\"\n\n[configurables]\ntool_list = [\"xopt/calculator:0.1.0\", \"xopt/websearch:1.0.0\"]\n```\n\n## Module Development\n\n### Creating a Module\n\n1. **Create module directory**:\n```bash\nmkdir my-module\ncd my-module\n```\n\n2. **Add module metadata** (`xopt.yaml`):\n```yaml\nmy-org/my-module@1.0.0:\n configurables:\n some_list: []\n tunables:\n some_param: \"default value\"\n```\n\n3. **Add dependencies** (`pyproject.toml`):\n```toml\n[project]\nname = \"my-module\"\nversion = \"1.0.0\"\ndependencies = [\n \"xopt @ file:///path/to/xoptpy\"\n]\n```\n\n4. **Implement module** (`my_module.py`):\n```python\nimport xopt\nfrom xopt.models import Module, StepResult\n\n@xopt.module\ndef my_module() -> Module:\n module = Module(\n name=\"my-org/my-module\",\n version=\"1.0.0\", \n description=\"My custom module\"\n )\n \n @xopt.step\n def process(input_data: str) -> StepResult:\n # Your module logic here\n return StepResult(\n action=\"response\",\n content=f\"Processed: {input_data}\"\n )\n \n module.register(\"process\", process, str)\n module.set_start_step(\"process\")\n return module\n\nxopt.register(my_module)\n```\n\n5. **Package and install**:\n```bash\npython3 -m xopt package .\npython3 -m xopt install my-org_my-module-1.0.0.xopt\n```\n\n## Examples\n\n### Math Calculation Chain\n```bash\npython3 -m xopt run \"xopt/react\" \"First calculate 12 * 15, then find the square root of that result\"\n```\n\n### Custom Configuration\n```bash\n# Create custom React configuration\ncat > .xopt/xopt-react.toml << EOF\n[tunables]\nreact_prompt = \"You are a precise mathematician. Always show detailed calculations.\"\n\n[configurables] \ntool_list = [\"xopt/calculator:0.1.0\"]\nEOF\n\n# Run with custom config\npython3 -m xopt prun \"xopt/react\" \"What is 25% of 480?\"\n```\n\n### Optimization Workflow\n```python\n# optimization.py - Example parameter tuning\nimport subprocess\nimport json\n\nprompts = [\n \"Be concise and direct.\",\n \"Show detailed step-by-step reasoning.\",\n \"Focus on accuracy over speed.\"\n]\n\nfor i, prompt in enumerate(prompts):\n config = {\"tunables\": {\"react_prompt\": f\"You are helpful. {prompt}\"}}\n \n result = subprocess.run([\n \"python3\", \"-m\", \"xopt\", \"run\", \"xopt/react\",\n \"Calculate the area of a circle with radius 7\",\n \"-c\", json.dumps(config)\n ], capture_output=True, text=True)\n \n print(f\"Config {i+1}: {result.stdout}\")\n```\n\n## Architecture\n\n- **Virtual Environment Isolation**: Each module gets its own Python environment (~/.xopt/modules/)\n- **Process-Level Execution**: Modules run in separate processes for crash safety\n- **Persistent Configuration**: Tunables stored in module directories survive restarts\n- **Dependency Management**: Poetry-style dependency resolution with .xopt/deps.toml\n- **Trace Generation**: Automatic execution tracing for debugging and optimization\n\n## Development\n\n```bash\n# Install in development mode\npoetry install\n\n# Run tests\npoetry run pytest\n\n# Package for distribution \npoetry build\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Submit a pull request\n\n## License\n\nMIT License - see LICENSE file for details.\n\n",
"bugtrack_url": null,
"license": null,
"summary": "eXtreme OPTimization - More optimizing agentic AI",
"version": "0.1.1",
"project_urls": {
"Documentation": "https://docs.xopt.ai",
"Homepage": "https://github.com/x-opt/xoptpy",
"Repository": "https://github.com/x-opt/xoptpy"
},
"split_keywords": [
"optimization",
" ai",
" agentic",
" llm",
" agents"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b5dc5f5d666e8b9ee3d0c6a0610c7c9aac5d9a813e74dd2bbaf7a3ecb7a3695c",
"md5": "50bb94c1ca53a450c649a9cb8dcf9c72",
"sha256": "67572184a17d20a5de38624d0e286e7c345dcf6fed85e177bae41ee16e764862"
},
"downloads": -1,
"filename": "xoptpy-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "50bb94c1ca53a450c649a9cb8dcf9c72",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.9",
"size": 19620,
"upload_time": "2025-08-01T13:27:30",
"upload_time_iso_8601": "2025-08-01T13:27:30.158846Z",
"url": "https://files.pythonhosted.org/packages/b5/dc/5f5d666e8b9ee3d0c6a0610c7c9aac5d9a813e74dd2bbaf7a3ecb7a3695c/xoptpy-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "914259a7895b988980e1fa57d12610ad6d7597f1e1679d6087aba059315193a9",
"md5": "ed982900ed25481795349de60d2e47c1",
"sha256": "294a289f3bb8579a95fd66ac316126495c54065d6dc61edbb587d231c6282798"
},
"downloads": -1,
"filename": "xoptpy-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "ed982900ed25481795349de60d2e47c1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.9",
"size": 18928,
"upload_time": "2025-08-01T13:27:31",
"upload_time_iso_8601": "2025-08-01T13:27:31.648666Z",
"url": "https://files.pythonhosted.org/packages/91/42/59a7895b988980e1fa57d12610ad6d7597f1e1679d6087aba059315193a9/xoptpy-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-01 13:27:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "x-opt",
"github_project": "xoptpy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "xoptpy"
}
