wizelit-sdk 0.1.30__tar.gz → 0.1.32__tar.gz

{wizelit_sdk-0.1.30 → wizelit_sdk-0.1.32}/Makefile

@@ -57,20 +57,20 @@ install-dev:
 # Run tests
 test:
 	@echo "Running tests..."
-	uv run pytest tests/ -v
+	uv run --with pytest pytest tests/ -v
 
 # Run code linting
 lint:
 	@echo "Running linting checks..."
-	uv run ruff check src/
+	uv run --with ruff ruff check src/
 	@echo "Running type checks..."
-	-uv run mypy src/ 2>/dev/null || echo "mypy not installed, skipping type checks"
+	-uv run --with mypy mypy src/ 2>/dev/null || echo "mypy not installed, skipping type checks"
 
 # Format code
 format:
 	@echo "Formatting code..."
-	uv run black src/ tests/
-	uv run ruff check --fix src/
+	uv run --with black black src/ tests/
+	uv run --with ruff ruff check --fix src/
 
 # Run all checks
 check: test lint
@@ -91,7 +91,7 @@ clean:
 # Build package
 build: clean
 	@echo "Building package..."
-	uv run python -m build
+	uv run --with build python -m build
 	@echo "Build complete! Files in dist/"
 
 # Check if VERSION is provided

wizelit_sdk-0.1.32/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: wizelit-sdk
+Version: 0.1.32
+Summary: Wizelit Agent Wrapper - Internal utility package
+Author-email: Your Name <your.email@company.com>
+Requires-Python: >=3.10
+Requires-Dist: asyncpg>=0.26.0
+Requires-Dist: click>=8.1.0
+Requires-Dist: fastmcp>=0.1.0
+Requires-Dist: redis>=4.5.0
+Requires-Dist: sqlalchemy>=1.4
+Requires-Dist: typeguard>=4.3.0
+Requires-Dist: typing-extensions>=4.0.0
+Provides-Extra: dev
+Requires-Dist: black>=22.0.0; extra == 'dev'
+Requires-Dist: build>=1.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: streaming
+Requires-Dist: redis>=4.5.0; extra == 'streaming'
+Description-Content-Type: text/markdown
+
+# wizelit-sdk
+
+Internal utility package for Wizelit Agent operations.
+
+> **New to Wizelit?** Start with the [**Quick Start Guide**](./QUICKSTART.md) to build your first agent in under 30 minutes!
+
+## Installation
+
+### Install from PyPI
+
+```bash
+uv pip install wizelit-sdk
+```
+
+### Add to pyproject.toml
+
+```toml
+[project]
+dependencies = [
+    "wizelit-sdk"
+]
+```
+
+## Quickstart
+
+1. Install the package (see above).
+2. Configure environment variables (see Configuration).
+3. Import and use the SDK from your app.
+
+### CLI
+
+The package also installs a small command-line tool named `wizelit-sdk` which helps scaffold and manage agent projects.
+
+Install and run the CLI:
+
+```bash
+# Install package (global or in virtualenv)
+pip install wizelit-sdk
+
+# Create a new project using a template (fast|slow|hybrid)
+wizelit-sdk init "My Agent" --template hybrid
+
+# Alternative (without wrapper):
+python -m wizelit_sdk.cli init "My Agent" --template hybrid
+```
+
+Useful commands:
+
+- `wizelit-sdk init <name> [--template fast|slow|hybrid]` — scaffold a new agent project
+- `wizelit-sdk scaffold <name>` — basic scaffold (older command)
+- `wizelit-sdk validate [path]` — validate project structure
+- `wizelit-sdk list-tools [path]` — list functions decorated with `@mcp.ingest`
+
+If you are developing locally, install editable and use the wrapper from your virtualenv:
+
+```bash
+# from repo root
+pip install -e .
+source .venv/bin/activate
+wizelit-sdk init "My Agent"
+```
+
+## Usage
+
+```python
+from wizelit_agent_wrapper import your_module
+
+# Use the wrapper
+result = your_module.function()
+```
+
+## SDK Guide
+
+### Basic import patterns
+
+```python
+from wizelit_sdk import database, exceptions
+from wizelit_sdk.agent_wrapper import agent_wrapper
+```
+
+### Initialize and call
+
+```python
+# Example: create a wrapper and call a method
+wrapper = agent_wrapper.WizelitAgentWrapper()
+result = wrapper.run()
+```
+
+### Error handling
+
+```python
+from wizelit_sdk.exceptions import WizelitError
+
+try:
+    wrapper.run()
+except WizelitError as exc:
+    # handle SDK-specific errors
+    print(exc)
+```
+
+## Configuration
+
+The SDK reads database configuration from the hosting application's environment. Provide these variables in the consuming project (e.g., via your app's .env or deployment secrets):
+
+- POSTGRES_USER
+- POSTGRES_PASSWORD
+- POSTGRES_HOST
+- POSTGRES_PORT
+- POSTGRES_DB
+
+You can also supply a full connection string via `DATABASE_URL` (overrides the individual fields). If using streaming/logging with Redis, set `REDIS_HOST`, `REDIS_PORT`, and optionally `REDIS_PASSWORD`.
+
+## Development
+
+### Setup Development Environment
+
+```bash
+# Clone repository
+git clone https://github.com/your-org/wizelit-sdk.git
+cd wizelit-sdk
+
+# Set up environment
+make setup
+
+# Activate virtual environment
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+
+# Install in development mode
+make install-dev
+```
+
+### Available Make Commands
+
+```bash
+make setup                  # Set up development environment
+make install                # Install package (production mode)
+make install-dev            # Install in development mode
+make test                   # Run tests
+make lint                   # Run code linting
+make format                 # Format code with black
+make check                  # Run tests and linting
+make clean                  # Clean build artifacts
+make build                  # Build package
+make release x.x.x          # Create new release (updates version, tags, pushes)
+make tag VERSION=x.x.x      # Create and push git tag
+make push                   # Push code and tags to remote
+make publish                # Publish package (run checks, build, push to remote)
+make publish-pypi           # Publish package to public PyPI
+make publish-artifactory    # Publish package to private Artifactory/PyPI
+make version                # Show current version
+make versions               # List all available versions
+```
+
+### Deploy to PyPI
+
+Use the built-in Makefile target (recommended):
+
+```bash
+make publish-pypi
+```
+
+This target will:
+
+1. Verify the git working tree is clean.
+2. Run tests and linting (`make check`).
+3. Build the package (`make build`).
+4. Upload the artifacts in `dist/` to PyPI via `twine`.
+
+Optional release/tag flow (before publishing):
+
+```bash
+# Interactive release flow (updates version, tags, pushes)
+make release x.x.x
+
+# Or tag a specific version
+make tag VERSION=x.x.x
+```
+
+Notes:
+
+- Ensure your PyPI credentials are configured locally (e.g., via $HOME/.pypirc or your preferred environment variables).
+- The package version must be unique on PyPI; if a version already exists, bump it and rebuild.
+
+## Contributing
+
+1. Create a feature branch
+2. Make your changes
+3. Run tests and linting: `make check`
+4. Commit your changes
+5. Push and create a pull request
+
+## Versioning
+
+We use [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** version for incompatible API changes
+- **MINOR** version for new functionality (backward compatible)
+- **PATCH** version for bug fixes
+
+See [CHANGELOG.md](CHANGELOG.md) for version history.

wizelit_sdk-0.1.32/QUICKSTART.md

@@ -0,0 +1,342 @@
+# Wizelit SDK Quick Start Guide
+
+Get your first Wizelit agent running in **under 30 minutes**. This guide takes approximately **5 minutes to read** and covers everything you need to build and deploy your first agent.
+
+---
+
+## What You'll Build
+
+By the end of this guide, you'll have a working agent that:
+
+- ✅ Exposes a reusable tool via REST API
+- ✅ Runs locally or in a container
+- ✅ Integrates with LLMs and other services
+
+---
+
+## Prerequisites
+
+- Python 3.8+
+- `pip` (Python package manager)
+- A terminal/command line
+- ~20 MB of disk space
+
+---
+
+## Step 1: Install the SDK
+
+### Option A: Install from PyPI (Recommended)
+
+```bash
+pip install wizelit-sdk
+```
+
+### Option B: Install from Source (for development)
+
+```bash
+git clone https://github.com/wizelit/wizelit-sdk.git
+cd wizelit-sdk
+pip install -e .
+```
+
+**Verify installation:**
+
+```bash
+wizelit --version
+```
+
+---
+
+## Step 2: Create Your First Agent
+
+Use the CLI to scaffold a new agent project:
+
+```bash
+wizelit init my-first-agent
+```
+
+This creates a directory with:
+
+```
+my-first-agent/
+├── main.py              # Your agent code
+├── requirements.txt     # Dependencies
+├── README.md           # Project docs
+└── .env.example        # Environment template
+```
+
+**What just happened:** The `init` command generated a "fast" agent template (default). This is a lightweight, synchronous agent perfect for quick APIs.
+
+---
+
+## Step 3: Install Dependencies
+
+Navigate to your project and install dependencies:
+
+```bash
+cd my-first-agent
+pip install -r requirements.txt
+```
+
+---
+
+## Step 4: Run Your Agent
+
+Start the agent server:
+
+```bash
+python main.py
+```
+
+You should see output like:
+
+```
+INFO:     Uvicorn running on http://0.0.0.0:8080
+```
+
+🎉 **Your agent is now running!**
+
+---
+
+## Step 5: Test Your Agent
+
+Open a **new terminal** while the agent is running.
+
+### Test with curl:
+
+```bash
+curl -X POST http://localhost:8080/invoke \
+  -H "Content-Type: application/json" \
+  -d '{"text": "Hello, Wizelit!"}'
+```
+
+**Expected response:**
+
+```json
+{ "echo": "Hello, Wizelit!" }
+```
+
+### Test with Python:
+
+```python
+import requests
+
+response = requests.post(
+    "http://localhost:8080/invoke",
+    json={"text": "Hello, Wizelit!"}
+)
+print(response.json())
+# Output: {"echo": "Hello, Wizelit!"}
+```
+
+---
+
+## Step 6: Customize Your Agent
+
+Edit `main.py` to add your own tools. Here's a simple example:
+
+### Example: Text Analysis Tool
+
+Replace the `example_tool` function with:
+
+```python
+@mcp.ingest(
+    is_long_running=False,
+    description="Analyze text sentiment and return statistics",
+    response_handling={"mode": "json"},
+)
+def analyze_text(text: str) -> dict:
+    """Analyze text and return word count and character count."""
+    words = len(text.split())
+    chars = len(text)
+    return {
+        "word_count": words,
+        "char_count": chars,
+        "avg_word_length": round(chars / words, 2) if words > 0 else 0
+    }
+```
+
+### Restart and Test:
+
+1. Stop your agent (Ctrl+C)
+2. Restart:
+   ```bash
+   python main.py
+   ```
+3. Test the new tool:
+
+   ```bash
+   curl -X POST http://localhost:8080/invoke \
+     -H "Content-Type: application/json" \
+     -d '{"text": "The quick brown fox jumps over the lazy dog"}'
+   ```
+
+   **Response:**
+
+   ```json
+   {
+     "word_count": 9,
+     "char_count": 44,
+     "avg_word_length": 4.89
+   }
+   ```
+
+---
+
+## Step 7: Explore Templates
+
+Wizelit provides three agent templates:
+
+### Fast Agent (Default)
+
+- **Use case:** Simple, synchronous operations
+- **Example:** Text processing, API proxying
+- **Command:** `wizelit init my-agent --template fast`
+
+### Slow Agent
+
+- **Use case:** Long-running async tasks
+- **Example:** File processing, ML inference, batch jobs
+- **Includes:** Redis for job queuing
+- **Command:** `wizelit init my-agent --template slow`
+
+Example slow agent function:
+
+```python
+@mcp.ingest(is_long_running=True, description="Process large file")
+async def process_file(filepath: str, job: Job) -> dict:
+    job.logger.info(f"Starting to process {filepath}")
+    # Your long-running work here
+    return {"status": "complete"}
+```
+
+### Hybrid Agent
+
+- **Use case:** Both fast and slow operations
+- **Example:** API with background jobs
+- **Command:** `wizelit init my-agent --template hybrid`
+
+---
+
+## Step 8: Validate Your Project
+
+Ensure your agent has all required files:
+
+```bash
+wizelit validate
+```
+
+Output:
+
+```
+✅ Project looks valid
+```
+
+---
+
+## Step 9: List Your Tools
+
+See all tools available in your agent:
+
+```bash
+wizelit list-tools
+```
+
+Output:
+
+```
+- analyze_text (in main.py)
+```
+
+---
+
+## Next Steps
+
+### 1. **Add Environment Configuration**
+
+Create a `.env` file from the template:
+
+```bash
+cp .env.example .env
+```
+
+For slow/hybrid agents with Redis:
+
+```bash
+REDIS_URL=redis://localhost:6379
+ENABLE_LOG_STREAMING=true
+```
+
+### 2. **Deploy to Production**
+
+- **Docker:** Add a `Dockerfile` (template coming soon)
+- **Cloud:** Deploy to AWS Lambda, Google Cloud Run, etc.
+- **MCP Server:** Use as a Model Context Protocol server
+
+### 3. **Integrate with LLMs**
+
+Register your agent with Claude, GPT, or other LLMs to use your tools.
+
+### 4. **Advanced Features**
+
+- Job tracking and streaming
+- Multiple tool signatures
+- Custom transport protocols
+- Database integration
+
+---
+
+## Troubleshooting
+
+### "ModuleNotFoundError: No module named 'wizelit_sdk'"
+
+```bash
+# Reinstall the SDK
+pip install --force-reinstall wizelit-sdk
+```
+
+### "Address already in use" (Port 8080)
+
+```bash
+# Use a different port
+python main.py --port 8090
+```
+
+### Agent not responding
+
+1. Check that the server is still running
+2. Verify the endpoint URL is correct
+3. Check logs for errors
+
+---
+
+## Examples & Resources
+
+- **Example Agents:** See `dzun-local/examples/` in the repo
+- **API Documentation:** See [API_DOCS.md](./API_DOCS.md)
+- **Architecture Guide:** See [ARCHITECTURE.md](./ARCHITECTURE.md)
+- **GitHub:** [wizelit/wizelit-sdk](https://github.com/wizelit/wizelit-sdk)
+
+---
+
+## Summary
+
+You now know how to:
+
+- ✅ Install Wizelit SDK
+- ✅ Create agents with templates
+- ✅ Run and test your agents locally
+- ✅ Add custom tools
+- ✅ Choose the right template for your use case
+
+**Estimated time to get here: ~20-25 minutes** 🚀
+
+---
+
+## Questions?
+
+- Check the [README.md](./README.md) for detailed docs
+- Review [INITIALIZATION_INSTRUCTION.MD](./INITIALIZATION_INSTRUCTION.MD) for advanced setup
+- Open an issue on GitHub
+
+Happy building! 🎉