mockworld 0.2.0__tar.gz

mockworld-0.2.0/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python3:*)"
+    ]
+  }
+}

mockworld-0.2.0/.gitignore

@@ -0,0 +1,101 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+*.egg-info/
+mockworld/_version.py

mockworld-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Handled Engineering
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mockworld-0.2.0/PKG-INFO

@@ -0,0 +1,320 @@
+Metadata-Version: 2.4
+Name: mockworld
+Version: 0.2.0
+Summary: World tests for AI agents - intercept and mock HTTP requests across services
+Project-URL: Homepage, https://github.com/handled-engineering/mockworld-python
+Project-URL: Documentation, https://github.com/handled-engineering/mockworld-python#readme
+Project-URL: Repository, https://github.com/handled-engineering/mockworld-python
+Project-URL: Issues, https://github.com/handled-engineering/mockworld-python/issues
+Author-email: Handled Engineering <engineering@handled.com>
+License: MIT
+License-File: LICENSE
+Keywords: agent,ai,http,interceptor,mocking,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.25
+Provides-Extra: dev
+Requires-Dist: httpx; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: responses; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mockworld-python
+
+> World tests for AI agents - intercept and mock HTTP requests across services
+
+[![PyPI version](https://badge.fury.io/py/mockworld.svg)](https://badge.fury.io/py/mockworld)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+mockworld intercepts HTTP requests from your AI agent and redirects them to mock endpoints. Configure which services to intercept, and mockworld handles the rest.
+
+## Installation
+
+```bash
+pip install mockworld
+```
+
+## Quick Start
+
+```python
+import mockworld
+
+# Configure connection to MockServer
+mockworld.configure(
+    base_url="https://api.mokra.ai/api",
+    api_key="your-api-key"
+)
+
+# Create a world with your services
+world = mockworld.mockworld("my test", "stripe", "shopify")
+
+# Run your agent
+def agent_code(services):
+    import requests
+    # Your agent code here - HTTP calls are automatically intercepted
+    requests.post(
+        "https://api.stripe.com/v1/charges",
+        json={"amount": 1000, "currency": "usd"}
+    )
+
+world.run(agent_code)
+
+# See what happened
+world.observe()
+
+# Assert outcomes
+world.assert_(
+    "a charge was created",
+    "no errors occurred"
+)
+```
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Your Agent Code                         │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │           world.run(lambda services:               │   │
+│  │               requests.post("https://api.stripe...│   │
+│  │           )                                        │   │
+│  └─────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   mockworld Interceptor                     │
+│                                                             │
+│   https://api.stripe.com/v1/charges                         │
+│                     ↓                                       │
+│   https://api.mokra.ai/api/mock/stripe/v1/charges           │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│              Mock Server (api.mokra.ai)                     │
+│                                                             │
+│    Records observations, returns mock responses,            │
+│    evaluates assertions, manages state                      │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Configuration
+
+### Direct Configuration
+
+```python
+mockworld.configure(
+    base_url="https://api.mokra.ai/api",
+    api_key="your-api-key"
+)
+```
+
+### Environment Variables
+
+```bash
+export MOCKWORLD_BASE_URL="https://api.mokra.ai/api"
+export MOCKWORLD_API_KEY="your-api-key"
+```
+
+### Auth Styles
+
+```python
+# Default: X-API-Key header (for mokra.ai)
+mockworld.configure(
+    api_key="your-api-key"
+)
+# Sends: X-API-Key: your-api-key
+
+# Bearer token auth
+mockworld.configure(
+    api_key="your-token",
+    auth_style="bearer"
+)
+# Sends: Authorization: Bearer your-token
+
+# Custom header
+mockworld.configure(
+    api_key="your-key",
+    auth_style="custom",
+    auth_header="X-Custom-Auth"
+)
+# Sends: X-Custom-Auth: your-key
+```
+
+## API Reference
+
+### `mockworld.mockworld(name, *services)`
+
+Create a new world with specified services.
+
+```python
+# String shorthand
+world = mockworld.mockworld("my test", "stripe", "shopify", "loop")
+
+# Attach existing mock server
+world = mockworld.mockworld("my test",
+    "stripe",
+    {"service_id": "shopify", "server_id": "existing-ms-id"}
+)
+```
+
+### `world.run(func)` / `with world.run():`
+
+Run your agent. All HTTP calls made during execution are intercepted and recorded by MockServer.
+
+```python
+# Function style
+def agent_code(services):
+    # Your agent code
+    requests.post("https://api.stripe.com/v1/charges", ...)
+
+world.run(agent_code)
+
+# Context manager style (recommended for pytest)
+with world.run():
+    requests.post("https://api.stripe.com/v1/charges", ...)
+```
+
+### `world.assert_(*assertions)`
+
+Assert conditions using natural language.
+
+```python
+results = world.assert_(
+    "customer charged once",
+    "no refund issued"
+)
+```
+
+### `world.observe()`
+
+Display observations recorded by MockServer.
+
+```python
+world.observe()
+```
+
+### `world.seed(func)`
+
+Pre-populate state before running the agent.
+
+```python
+def setup(s):
+    s.shopify.orders.create({"id": "order-123", "total": 99.99})
+
+world.seed(setup)
+```
+
+### `world.state(mock_server_id=None)`
+
+Get current state of a mock server.
+
+```python
+state = world.state()
+state.total                    # => 5
+state.resource_types           # => ["products", "orders"]
+state["products"].count        # => 3
+state["products"].records      # => [StateRecord, ...]
+state["products"].find_by_id("prod-123")
+```
+
+## Service Mappings
+
+mockworld uses YAML files to map hosts to service slugs. The default mappings for mokra.ai are included.
+
+### Custom Mappings
+
+```python
+from mockworld import ServiceMapper
+
+# Add a single mapping
+ServiceMapper.add_mapping("api.myservice.com", "myservice")
+
+# Load mappings from a YAML file
+ServiceMapper.load_mappings("path/to/custom.yml")
+
+# Load and replace all mappings
+ServiceMapper.load_mappings("path/to/custom.yml", replace=True)
+```
+
+### Custom YAML Format
+
+```yaml
+# custom_mappings.yml
+api.myservice.com: myservice
+api.another.com: another
+*.internal.mycompany.com: internal
+```
+
+### Supporting Other Mock Servers
+
+Create a YAML file in the mappings directory named after your provider:
+
+```yaml
+# my_provider.yml
+api.stripe.com: stripe
+api.custom.com: custom
+```
+
+Then load it:
+
+```python
+from mockworld import ServiceMapper
+
+ServiceMapper.load_provider("my_provider")
+```
+
+## Pytest Integration
+
+mockworld works seamlessly with pytest:
+
+```python
+# conftest.py
+import pytest
+import mockworld
+import os
+
+@pytest.fixture(autouse=True)
+def configure_mockworld():
+    mockworld.configure(api_key=os.environ["MOCKWORLD_API_KEY"])
+```
+
+```python
+# test_refund.py
+from mockworld import mockworld
+
+def test_refund_service():
+    world = mockworld(name="Refund test", services_list=["stripe"])
+
+    with world.run():
+        # Your code that calls Stripe API
+        RefundService.process(payment_id="pi_123", amount=5000)
+
+    world.assert_("a refund was created")
+    world.assert_("refund amount is $50")
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT