wauldo 0.1.0__tar.gz

wauldo-0.1.0/.editorconfig

@@ -0,0 +1,11 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+indent_style = space
+indent_size = 4
+
+[*.{json,yml,yaml,toml}]
+indent_size = 2

wauldo-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+uv.lock
+.venv/

wauldo-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to the Wauldo Python SDK.
+
+## [0.1.0] - 2026-03-16
+
+### Added
+- `HttpClient` — REST API client (OpenAI-compatible)
+  - `chat()`, `chat_simple()`, `chat_stream()`, `list_models()`, `embeddings()`
+  - `rag_upload()`, `rag_query()`, `rag_ask()`
+  - `orchestrate()`, `orchestrate_parallel()`
+- `AgentClient` / `AsyncAgentClient` — MCP client (sync + async)
+  - `reason()`, `extract_concepts()`, `plan_task()`
+  - `chunk_document()`, `retrieve_context()`, `summarize()`
+  - `search_knowledge()`, `add_to_knowledge()`
+- `Conversation` — automatic chat history management
+- `MockHttpClient` — offline testing without server
+- Retry with exponential backoff (429/503/network errors)
+- Structured logging via `logging.getLogger("wauldo")`
+- Pydantic v2 response validation on all endpoints
+- Full type hints + py.typed (PEP 561)
+- Per-request `timeout_ms` override on `chat()`, `chat_simple()`, `rag_upload()`
+- Event hooks: `on_request`, `on_response`, `on_error` callbacks

wauldo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Wauldo Team
+
+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.

wauldo-0.1.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: wauldo
+Version: 0.1.0
+Summary: Official Python SDK for Wauldo — Verified AI answers from your documents
+Project-URL: Homepage, https://wauldo.com
+Project-URL: Documentation, https://wauldo.com/docs
+Project-URL: Repository, https://github.com/wauldo/wauldo-sdk-python
+Project-URL: Bug Tracker, https://github.com/wauldo/wauldo-sdk-python/issues
+Project-URL: RapidAPI, https://rapidapi.com/binnewzzin/api/smart-rag-api
+Project-URL: Source, https://github.com/wauldo/wauldo-sdk-python
+Author-email: Wauldo Team <contact@wauldo.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,api,chatgpt,gdpr,llm,machine-learning,nlp,openai,privacy,rapidapi
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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 :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Wauldo Python SDK
+
+[![PyPI](https://img.shields.io/pypi/v/wauldo.svg)](https://pypi.org/project/wauldo/)
+[![Downloads](https://img.shields.io/pypi/dm/wauldo.svg)](https://pypi.org/project/wauldo/)
+[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
+
+> **Verified AI answers from your documents.** Every response includes source citations, confidence scores, and an audit trail — or we don't answer at all.
+
+Official Python SDK for the [Wauldo API](https://wauldo.com) — the AI inference layer with smart model routing and zero hallucinations.
+
+## Why Wauldo?
+
+- **Zero hallucinations** — every answer is verified against source documents
+- **Smart model routing** — auto-selects the cheapest model that meets quality (save 40-80% on AI costs)
+- **One API, 7+ providers** — OpenAI, Anthropic, Google, Qwen, Meta, Mistral, DeepSeek with automatic fallback
+- **OpenAI-compatible** — swap your `base_url`, keep your existing code
+- **Full audit trail** — confidence score, grounded status, model used, latency on every response
+
+## Quick Start
+
+```python
+from wauldo import HttpClient
+
+client = HttpClient(base_url="https://api.wauldo.com", api_key="YOUR_API_KEY")
+
+reply = client.chat_simple("auto", "What is Python?")
+print(reply)
+```
+
+## Installation
+
+```bash
+pip install wauldo
+```
+
+**Requirements:** Python 3.9+
+
+## Features
+
+### Chat Completions
+
+```python
+from wauldo import HttpClient, ChatRequest, HttpChatMessage
+
+client = HttpClient(base_url="https://api.wauldo.com", api_key="YOUR_API_KEY")
+
+request = ChatRequest(
+    model="auto",
+    messages=[
+        HttpChatMessage.system("You are a helpful assistant."),
+        HttpChatMessage.user("Explain Python decorators"),
+    ],
+)
+response = client.chat(request)
+print(response.choices[0].message.content)
+```
+
+### RAG — Upload & Query
+
+```python
+# Upload a document
+upload = client.rag_upload(content="Contract text here...", filename="contract.txt")
+print(f"Indexed {upload.chunks_count} chunks")
+
+# Query with verified answer
+result = client.rag_query("What are the payment terms?")
+print(f"Answer: {result.answer}")
+print(f"Confidence: {result.get_confidence():.0%}")
+print(f"Grounded: {result.audit.grounded}")
+for source in result.sources:
+    print(f"  Source ({source.score:.0%}): {source.content[:80]}")
+```
+
+### Streaming (SSE)
+
+```python
+from wauldo import ChatRequest, HttpChatMessage
+
+request = ChatRequest(model="auto", messages=[HttpChatMessage.user("Hello!")])
+for chunk in client.chat_stream(request):
+    print(chunk, end="", flush=True)
+```
+
+### Conversation Helper
+
+```python
+conv = client.conversation(system="You are an expert on Python.", model="auto")
+reply = conv.say("What are list comprehensions?")
+follow_up = conv.say("Give me a nested example")
+```
+
+## Error Handling
+
+```python
+from wauldo import WauldoError, ServerError, AgentTimeoutError
+
+try:
+    response = client.chat(ChatRequest.quick("auto", "Hello"))
+except ServerError as e:
+    print(f"Server error: {e}")
+except AgentTimeoutError:
+    print("Request timed out")
+except WauldoError as e:
+    print(f"SDK error: {e}")
+```
+
+## RapidAPI
+
+```python
+client = HttpClient(
+    base_url="https://api.wauldo.com",
+    headers={
+        "X-RapidAPI-Key": "YOUR_RAPIDAPI_KEY",
+        "X-RapidAPI-Host": "smart-rag-api.p.rapidapi.com",
+    },
+)
+```
+
+Get your free API key (300 req/month): [RapidAPI](https://rapidapi.com/binnewzzin/api/smart-rag-api)
+
+## Links
+
+- [Website](https://wauldo.com)
+- [Documentation](https://wauldo.com/docs)
+- [Live Demo](https://api.wauldo.com/demo)
+- [Cost Calculator](https://wauldo.com/calculator)
+- [Status](https://wauldo.com/status)
+
+## Contributing
+
+Found a bug? Have a feature request? [Open an issue](https://github.com/wauldo/wauldo-sdk-python/issues).
+
+## License
+
+MIT — see [LICENSE](./LICENSE)

wauldo-0.1.0/README.md

@@ -0,0 +1,136 @@
+# Wauldo Python SDK
+
+[![PyPI](https://img.shields.io/pypi/v/wauldo.svg)](https://pypi.org/project/wauldo/)
+[![Downloads](https://img.shields.io/pypi/dm/wauldo.svg)](https://pypi.org/project/wauldo/)
+[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
+
+> **Verified AI answers from your documents.** Every response includes source citations, confidence scores, and an audit trail — or we don't answer at all.
+
+Official Python SDK for the [Wauldo API](https://wauldo.com) — the AI inference layer with smart model routing and zero hallucinations.
+
+## Why Wauldo?
+
+- **Zero hallucinations** — every answer is verified against source documents
+- **Smart model routing** — auto-selects the cheapest model that meets quality (save 40-80% on AI costs)
+- **One API, 7+ providers** — OpenAI, Anthropic, Google, Qwen, Meta, Mistral, DeepSeek with automatic fallback
+- **OpenAI-compatible** — swap your `base_url`, keep your existing code
+- **Full audit trail** — confidence score, grounded status, model used, latency on every response
+
+## Quick Start
+
+```python
+from wauldo import HttpClient
+
+client = HttpClient(base_url="https://api.wauldo.com", api_key="YOUR_API_KEY")
+
+reply = client.chat_simple("auto", "What is Python?")
+print(reply)
+```
+
+## Installation
+
+```bash
+pip install wauldo
+```
+
+**Requirements:** Python 3.9+
+
+## Features
+
+### Chat Completions
+
+```python
+from wauldo import HttpClient, ChatRequest, HttpChatMessage
+
+client = HttpClient(base_url="https://api.wauldo.com", api_key="YOUR_API_KEY")
+
+request = ChatRequest(
+    model="auto",
+    messages=[
+        HttpChatMessage.system("You are a helpful assistant."),
+        HttpChatMessage.user("Explain Python decorators"),
+    ],
+)
+response = client.chat(request)
+print(response.choices[0].message.content)
+```
+
+### RAG — Upload & Query
+
+```python
+# Upload a document
+upload = client.rag_upload(content="Contract text here...", filename="contract.txt")
+print(f"Indexed {upload.chunks_count} chunks")
+
+# Query with verified answer
+result = client.rag_query("What are the payment terms?")
+print(f"Answer: {result.answer}")
+print(f"Confidence: {result.get_confidence():.0%}")
+print(f"Grounded: {result.audit.grounded}")
+for source in result.sources:
+    print(f"  Source ({source.score:.0%}): {source.content[:80]}")
+```
+
+### Streaming (SSE)
+
+```python
+from wauldo import ChatRequest, HttpChatMessage
+
+request = ChatRequest(model="auto", messages=[HttpChatMessage.user("Hello!")])
+for chunk in client.chat_stream(request):
+    print(chunk, end="", flush=True)
+```
+
+### Conversation Helper
+
+```python
+conv = client.conversation(system="You are an expert on Python.", model="auto")
+reply = conv.say("What are list comprehensions?")
+follow_up = conv.say("Give me a nested example")
+```
+
+## Error Handling
+
+```python
+from wauldo import WauldoError, ServerError, AgentTimeoutError
+
+try:
+    response = client.chat(ChatRequest.quick("auto", "Hello"))
+except ServerError as e:
+    print(f"Server error: {e}")
+except AgentTimeoutError:
+    print("Request timed out")
+except WauldoError as e:
+    print(f"SDK error: {e}")
+```
+
+## RapidAPI
+
+```python
+client = HttpClient(
+    base_url="https://api.wauldo.com",
+    headers={
+        "X-RapidAPI-Key": "YOUR_RAPIDAPI_KEY",
+        "X-RapidAPI-Host": "smart-rag-api.p.rapidapi.com",
+    },
+)
+```
+
+Get your free API key (300 req/month): [RapidAPI](https://rapidapi.com/binnewzzin/api/smart-rag-api)
+
+## Links
+
+- [Website](https://wauldo.com)
+- [Documentation](https://wauldo.com/docs)
+- [Live Demo](https://api.wauldo.com/demo)
+- [Cost Calculator](https://wauldo.com/calculator)
+- [Status](https://wauldo.com/status)
+
+## Contributing
+
+Found a bug? Have a feature request? [Open an issue](https://github.com/wauldo/wauldo-sdk-python/issues).
+
+## License
+
+MIT — see [LICENSE](./LICENSE)

wauldo-0.1.0/examples/basic_chat.py

@@ -0,0 +1,28 @@
+"""Basic chat completion using the Wauldo HttpClient."""
+
+from wauldo import HttpClient, ChatRequest, HttpChatMessage
+
+def main() -> None:
+    client = HttpClient(base_url="http://localhost:3000")
+
+    # Quick one-liner chat
+    reply = client.chat_simple("qwen2.5:7b", "What is Rust?")
+    print(f"Simple reply: {reply[:120]}...")
+
+    # Full request with parameters
+    request = ChatRequest(
+        model="qwen2.5:7b",
+        messages=[
+            HttpChatMessage.system("You are a concise assistant."),
+            HttpChatMessage.user("Explain async/await in 2 sentences."),
+        ],
+        temperature=0.3,
+        max_tokens=200,
+    )
+    response = client.chat(request)
+    print(f"Model: {response.model}")
+    print(f"Reply: {response.choices[0].message.content}")
+    print(f"Tokens used: {response.usage.total_tokens}")
+
+if __name__ == "__main__":
+    main()

wauldo-0.1.0/examples/rag_workflow.py

@@ -0,0 +1,25 @@
+"""RAG workflow: upload a document then query the knowledge base."""
+
+from wauldo import HttpClient
+
+def main() -> None:
+    client = HttpClient(base_url="http://localhost:3000")
+
+    # Upload a document for RAG indexing
+    doc = (
+        "Rust is a systems programming language focused on safety and performance. "
+        "It prevents data races at compile time through its ownership system. "
+        "The borrow checker enforces memory safety without a garbage collector."
+    )
+    upload = client.rag_upload(content=doc, filename="rust_intro.txt")
+    print(f"Uploaded: id={upload.document_id}, chunks={upload.chunks_count}")
+
+    # Query the knowledge base
+    result = client.rag_query("How does Rust ensure memory safety?", top_k=3)
+    print(f"\nAnswer: {result.answer}")
+    print(f"\nSources ({len(result.sources)}):")
+    for src in result.sources:
+        print(f"  - [{src.score:.2f}] {src.content[:80]}...")
+
+if __name__ == "__main__":
+    main()

wauldo-0.1.0/examples/streaming_chat.py

@@ -0,0 +1,28 @@
+"""SSE streaming chat completion using the Wauldo HttpClient."""
+
+import sys
+from wauldo import HttpClient, ChatRequest, HttpChatMessage
+
+def main() -> None:
+    client = HttpClient(base_url="http://localhost:3000")
+
+    request = ChatRequest(
+        model="qwen2.5:7b",
+        messages=[
+            HttpChatMessage.system("You are a helpful assistant."),
+            HttpChatMessage.user("Write a haiku about Rust programming."),
+        ],
+        temperature=0.7,
+    )
+
+    print("Streaming response: ", end="", flush=True)
+    token_count = 0
+    for chunk in client.chat_stream(request):
+        sys.stdout.write(chunk)
+        sys.stdout.flush()
+        token_count += 1
+
+    print(f"\n\nReceived {token_count} chunks.")
+
+if __name__ == "__main__":
+    main()

wauldo-0.1.0/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "wauldo"
+version = "0.1.0"
+description = "Official Python SDK for Wauldo — Verified AI answers from your documents"
+readme = "README.md"
+license = {text = "MIT"}
+license-files = ["LICENSE"]
+authors = [
+    {name = "Wauldo Team", email = "contact@wauldo.com"}
+]
+keywords = ["ai", "llm", "openai", "privacy", "gdpr", "chatgpt", "api", "rapidapi", "nlp", "machine-learning"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+requires-python = ">=3.9"
+dependencies = [
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-cov>=4.0",
+    "mypy>=1.0.0",
+    "ruff>=0.1.0",
+]
+
+[project.urls]
+Homepage = "https://wauldo.com"
+Documentation = "https://wauldo.com/docs"
+Repository = "https://github.com/wauldo/wauldo-sdk-python"
+"Bug Tracker" = "https://github.com/wauldo/wauldo-sdk-python/issues"
+RapidAPI = "https://rapidapi.com/binnewzzin/api/smart-rag-api"
+Source = "https://github.com/wauldo/wauldo-sdk-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/wauldo"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+filterwarnings = [
+    "ignore::DeprecationWarning",
+]
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "ANN", "B", "C4", "SIM"]
+ignore = ["ANN101", "ANN102"]

wauldo-0.1.0/src/wauldo/__init__.py

@@ -0,0 +1,89 @@
+"""
+Wauldo Python SDK
+
+Two client interfaces:
+- AgentClient / AsyncAgentClient — MCP server (stdio JSON-RPC) for reasoning, planning, tools
+- HttpClient — REST API (OpenAI-compatible) for chat, embeddings, RAG, orchestrator
+"""
+
+from .client import AgentClient, AsyncAgentClient
+from .conversation import Conversation
+from .exceptions import (
+    AgentConnectionError,
+    AgentTimeoutError,
+    ServerError,
+    ToolNotFoundError,
+    ValidationError,
+    WauldoError,
+)
+from .http_client import HttpClient
+from .http_types import (
+    ChatMessage as HttpChatMessage,
+)
+from .http_types import (
+    ChatRequest,
+    ChatResponse,
+    EmbeddingResponse,
+    ModelList,
+    OrchestratorResponse,
+    RagAuditInfo,
+    RagQueryResponse,
+    RagSource,
+    RagUploadResponse,
+)
+from .mock_client import MockHttpClient
+from .models import (
+    Chunk,
+    ChunkResult,
+    Concept,
+    ConceptResult,
+    GraphNode,
+    KnowledgeGraphResult,
+    PlanResult,
+    PlanStep,
+    ReasoningResult,
+    RetrievalResult,
+    ToolDefinition,
+    ToolsListResult,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    # MCP Clients
+    "AgentClient",
+    "AsyncAgentClient",
+    # HTTP Client
+    "HttpClient",
+    "MockHttpClient",
+    "Conversation",
+    "ChatRequest",
+    "ChatResponse",
+    "HttpChatMessage",
+    "EmbeddingResponse",
+    "ModelList",
+    "OrchestratorResponse",
+    "RagAuditInfo",
+    "RagQueryResponse",
+    "RagSource",
+    "RagUploadResponse",
+    # Exceptions
+    "WauldoError",
+    "AgentConnectionError",
+    "AgentTimeoutError",
+    "ServerError",
+    "ToolNotFoundError",
+    "ValidationError",
+    # MCP Models
+    "ReasoningResult",
+    "ConceptResult",
+    "Concept",
+    "ChunkResult",
+    "Chunk",
+    "RetrievalResult",
+    "KnowledgeGraphResult",
+    "PlanResult",
+    "PlanStep",
+    "GraphNode",
+    "ToolDefinition",
+    "ToolsListResult",
+]