praixis 0.1.0__tar.gz

praixis-0.1.0/.claude/settings.local.json

@@ -0,0 +1,17 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(ls \"C:\\\\Users\\\\meramirez\\\\Desktop\\\\PythonProjects\\\\PraixisEngine\")",
+      "Read(//c/Users/meramirez/Desktop/PythonProjects/**)",
+      "Bash(uv run *)",
+      "Bash(PRAIXIS_KEY='praixis_HZU7igk-i6LPxzPJNPv6V-3iA3O8qDBprRbkZOoTKog' PRAIXIS_URL='http://172.30.1.144:8080' uv run --no-project python _live_check.py)",
+      "Bash(rm -f praixis/resources/admin.py praixis/aio/resources/admin.py)",
+      "Bash(rm -f praixis/resources/__pycache__/admin*.pyc praixis/aio/resources/__pycache__/admin*.pyc)",
+      "Bash(PRAIXIS_KEY=praixis_HZU7igk-i6LPxzPJNPv6V-3iA3O8qDBprRbkZOoTKog uv run --no-project python -c ' *)",
+      "Bash(New-Item -ItemType File praixis/py.typed)",
+      "Bash(Out-Null)",
+      "Bash(Test-Path praixis/py.typed)",
+      "Bash(uv build *)"
+    ]
+  }
+}

praixis-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.mypy_cache/
+.pytest_cache/
+uv.lock
+
+# Editor / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# Internal notes (not for distribution)
+NOTES.md

praixis-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Michael E. Ramirez A.
+
+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.

praixis-0.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: praixis
+Version: 0.1.0
+Summary: Zero-dependency Python client for the Praixis Engine API
+Project-URL: Homepage, https://github.com/mettjs/praixis-python
+Project-URL: Repository, https://github.com/mettjs/praixis-python
+Project-URL: Issues, https://github.com/mettjs/praixis-python/issues
+Author: Michael E. Ramirez A.
+License: MIT
+License-File: LICENSE
+Keywords: ai,llm,praixis,rag
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: async
+Requires-Dist: httpx>=0.24; extra == 'async'
+Description-Content-Type: text/markdown
+
+# Praixis Engine — Python Client
+
+A lightweight Python client for the Praixis Engine API, in both **sync** and
+**async** flavors.
+
+- **`PraixisClient`** — synchronous, **zero dependencies**, built entirely on
+  the standard library (`urllib`, `json`, `uuid`), so an upstream package
+  release can never break it.
+- **`AsyncPraixisClient`** — async/await, built on `httpx` (the only optional
+  dependency). Imported lazily, so the sync client stays dependency-free.
+- Same surface in both: resource-grouped `client.chat` and `client.rag` — chat
+  + file summary, and RAG ingest/ask/embed/compare.
+
+> The companion Node.js client lives in its own repository.
+
+## Installation
+
+```bash
+pip install praixis            # sync client only, zero dependencies
+pip install "praixis[async]"   # also installs httpx for the async client
+```
+
+Or vendor the `praixis/` package directly into your project — the sync client
+has no deps.
+
+Requires Python 3.10+.
+
+## Authentication
+
+Every endpoint uses an app-level API key sent as the `X-API-Key` header.
+
+```python
+from praixis import PraixisClient
+
+client = PraixisClient("http://localhost:8080", "your-api-key")
+```
+
+> Admin/system routes (`/api/system/*`, HTTP Basic auth) are intentionally **not**
+> part of this SDK. They already have a browser UI, and baking admin credentials
+> into application code would be a security anti-pattern. The `X-API-Key` this
+> SDK uses is an app-level credential, not an admin one.
+
+## Chat
+
+```python
+# Start a conversation
+reply = client.chat.send("Hello, world!")
+print(reply["session_id"], reply["response"])
+
+# Continue it
+client.chat.send("And again?", session_id=reply["session_id"])
+
+# JSON-mode response, custom system prompt
+client.chat.send("List 3 colors", response_format="json", system_prompt="Be terse")
+
+# Sessions
+client.chat.list_sessions()          # -> [session_id, ...]
+client.chat.get_history(session_id)  # -> {"session_id", "history": [...]}
+client.chat.clear_history(session_id)
+
+# Summarize an uploaded file (path, or (filename, content[, content_type]))
+client.chat.summarize_file("report.pdf")
+client.chat.summarize_file(("notes.txt", "raw text here"))
+```
+
+> **Note on streaming:** the server streams chat and RAG answers as
+> `text/event-stream`, not JSON. This client buffers the full response and
+> parses the leading marker lines (`[SESSION_ID:...]`, and for RAG
+> `[SEARCH_QUERY:...]` / `[SOURCES:...]`) out of the body for you, so
+> `chat.send` returns `{"session_id", "response", "response_format"}` and
+> `rag.ask` returns `{"answer", "sources", "session_id", "search_query"}`.
+> Buffering is the right default for scripts and backends; token-by-token
+> iteration is not yet exposed.
+
+## RAG
+
+```python
+# Ingest one or many documents into a collection
+client.rag.upload("manual.pdf", collection_name="docs")
+client.rag.upload([("a.txt", "..."), ("b.txt", "...")], collection_name="docs")
+
+# Ask a question grounded in a collection
+ans = client.rag.ask("What does the manual say about setup?", collection_name="docs")
+print(ans)
+
+# Embeddings, listing, deletion, compare, summarize
+client.rag.embed("some text")
+client.rag.list_collections()
+client.rag.list_files("docs")
+client.rag.delete_file("docs", "a.txt")
+client.rag.delete_collection("docs")
+client.rag.compare("docs", "a.txt", "b.txt")
+client.rag.summarize_document("docs", "manual.pdf")
+```
+
+## Error handling
+
+```python
+from praixis import (
+    APIError, AuthenticationError, NotFoundError,
+    RateLimitError, APIConnectionError,
+)
+
+try:
+    client.chat.send("hi")
+except AuthenticationError:
+    ...          # 401 / 403
+except NotFoundError:
+    ...          # 404
+except RateLimitError:
+    ...          # 429 (per-route limits)
+except APIError as e:
+    print(e.status_code, e.detail)
+except APIConnectionError:
+    ...          # never reached the server
+```
+
+All exceptions inherit from `praixis.PraixisError`.
+
+## Testing
+
+Both suites run against a standard-library mock HTTP server — no network needed.
+
+```bash
+# Sync client — zero dependencies
+uv run --no-project python tests/test_client.py
+
+# Async client — needs httpx
+uv run --with httpx python tests/test_async_client.py
+```
+
+The async suite also asserts that the sync and async resources expose an
+identical set of methods, so the two clients can't silently drift apart.
+
+## Privacy note
+
+This client transmits whatever you pass to it (prompts, documents, session IDs)
+to the configured Praixis Engine server. Those payloads may contain personal
+data — handle them according to your own privacy obligations. The client stores
+nothing locally and adds no telemetry.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

praixis-0.1.0/README.md

@@ -0,0 +1,144 @@
+# Praixis Engine — Python Client
+
+A lightweight Python client for the Praixis Engine API, in both **sync** and
+**async** flavors.
+
+- **`PraixisClient`** — synchronous, **zero dependencies**, built entirely on
+  the standard library (`urllib`, `json`, `uuid`), so an upstream package
+  release can never break it.
+- **`AsyncPraixisClient`** — async/await, built on `httpx` (the only optional
+  dependency). Imported lazily, so the sync client stays dependency-free.
+- Same surface in both: resource-grouped `client.chat` and `client.rag` — chat
+  + file summary, and RAG ingest/ask/embed/compare.
+
+> The companion Node.js client lives in its own repository.
+
+## Installation
+
+```bash
+pip install praixis            # sync client only, zero dependencies
+pip install "praixis[async]"   # also installs httpx for the async client
+```
+
+Or vendor the `praixis/` package directly into your project — the sync client
+has no deps.
+
+Requires Python 3.10+.
+
+## Authentication
+
+Every endpoint uses an app-level API key sent as the `X-API-Key` header.
+
+```python
+from praixis import PraixisClient
+
+client = PraixisClient("http://localhost:8080", "your-api-key")
+```
+
+> Admin/system routes (`/api/system/*`, HTTP Basic auth) are intentionally **not**
+> part of this SDK. They already have a browser UI, and baking admin credentials
+> into application code would be a security anti-pattern. The `X-API-Key` this
+> SDK uses is an app-level credential, not an admin one.
+
+## Chat
+
+```python
+# Start a conversation
+reply = client.chat.send("Hello, world!")
+print(reply["session_id"], reply["response"])
+
+# Continue it
+client.chat.send("And again?", session_id=reply["session_id"])
+
+# JSON-mode response, custom system prompt
+client.chat.send("List 3 colors", response_format="json", system_prompt="Be terse")
+
+# Sessions
+client.chat.list_sessions()          # -> [session_id, ...]
+client.chat.get_history(session_id)  # -> {"session_id", "history": [...]}
+client.chat.clear_history(session_id)
+
+# Summarize an uploaded file (path, or (filename, content[, content_type]))
+client.chat.summarize_file("report.pdf")
+client.chat.summarize_file(("notes.txt", "raw text here"))
+```
+
+> **Note on streaming:** the server streams chat and RAG answers as
+> `text/event-stream`, not JSON. This client buffers the full response and
+> parses the leading marker lines (`[SESSION_ID:...]`, and for RAG
+> `[SEARCH_QUERY:...]` / `[SOURCES:...]`) out of the body for you, so
+> `chat.send` returns `{"session_id", "response", "response_format"}` and
+> `rag.ask` returns `{"answer", "sources", "session_id", "search_query"}`.
+> Buffering is the right default for scripts and backends; token-by-token
+> iteration is not yet exposed.
+
+## RAG
+
+```python
+# Ingest one or many documents into a collection
+client.rag.upload("manual.pdf", collection_name="docs")
+client.rag.upload([("a.txt", "..."), ("b.txt", "...")], collection_name="docs")
+
+# Ask a question grounded in a collection
+ans = client.rag.ask("What does the manual say about setup?", collection_name="docs")
+print(ans)
+
+# Embeddings, listing, deletion, compare, summarize
+client.rag.embed("some text")
+client.rag.list_collections()
+client.rag.list_files("docs")
+client.rag.delete_file("docs", "a.txt")
+client.rag.delete_collection("docs")
+client.rag.compare("docs", "a.txt", "b.txt")
+client.rag.summarize_document("docs", "manual.pdf")
+```
+
+## Error handling
+
+```python
+from praixis import (
+    APIError, AuthenticationError, NotFoundError,
+    RateLimitError, APIConnectionError,
+)
+
+try:
+    client.chat.send("hi")
+except AuthenticationError:
+    ...          # 401 / 403
+except NotFoundError:
+    ...          # 404
+except RateLimitError:
+    ...          # 429 (per-route limits)
+except APIError as e:
+    print(e.status_code, e.detail)
+except APIConnectionError:
+    ...          # never reached the server
+```
+
+All exceptions inherit from `praixis.PraixisError`.
+
+## Testing
+
+Both suites run against a standard-library mock HTTP server — no network needed.
+
+```bash
+# Sync client — zero dependencies
+uv run --no-project python tests/test_client.py
+
+# Async client — needs httpx
+uv run --with httpx python tests/test_async_client.py
+```
+
+The async suite also asserts that the sync and async resources expose an
+identical set of methods, so the two clients can't silently drift apart.
+
+## Privacy note
+
+This client transmits whatever you pass to it (prompts, documents, session IDs)
+to the configured Praixis Engine server. Those payloads may contain personal
+data — handle them according to your own privacy obligations. The client stores
+nothing locally and adds no telemetry.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

praixis-0.1.0/praixis/__init__.py

@@ -0,0 +1,63 @@
+"""Praixis Engine Python client.
+
+The synchronous :class:`PraixisClient` is built entirely on the standard
+library, so it has zero dependencies and upstream package releases can never
+break it::
+
+    from praixis import PraixisClient
+
+    client = PraixisClient("http://localhost:8080", "your-api-key")
+    print(client.chat.send("Hello")["response"])
+
+An :class:`AsyncPraixisClient` is also available for async/await code. It is
+backed by httpx, the SDK's only (optional) dependency - install it with
+``pip install praixis[async]``. The import is lazy, so httpx is required only if
+you actually use the async client; ``import praixis`` alone never needs it::
+
+    from praixis import AsyncPraixisClient
+
+    async with AsyncPraixisClient("http://localhost:8080", "your-api-key") as client:
+        print((await client.chat.send("Hello"))["response"])
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .client import PraixisClient
+from .errors import (
+    APIConnectionError,
+    APIError,
+    AuthenticationError,
+    NotFoundError,
+    PraixisError,
+    RateLimitError,
+)
+
+if TYPE_CHECKING:
+    # Give type checkers / IDEs the symbol without importing httpx at runtime.
+    from .aio import AsyncPraixisClient
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "PraixisClient",
+    "AsyncPraixisClient",
+    "PraixisError",
+    "APIError",
+    "APIConnectionError",
+    "AuthenticationError",
+    "NotFoundError",
+    "RateLimitError",
+    "__version__",
+]
+
+
+def __getattr__(name: str) -> object:
+    # Lazily resolve the async client so importing praixis never pulls in httpx
+    # unless the async client is actually requested.
+    if name == "AsyncPraixisClient":
+        from .aio import AsyncPraixisClient
+
+        return AsyncPraixisClient
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

praixis-0.1.0/praixis/_files.py

@@ -0,0 +1,45 @@
+"""Helpers for turning caller-supplied files into multipart parts."""
+
+from __future__ import annotations
+
+import os
+from typing import Union
+
+from ._transport import FilePart
+
+# What a caller may hand us for a single file:
+#   * a path on disk (str)
+#   * a (filename, content) pair
+#   * a (filename, content, content_type) triple
+FileInput = Union[str, tuple]
+
+_DEFAULT_CONTENT_TYPE = "application/octet-stream"
+
+
+def to_part(item: FileInput, field_name: str) -> FilePart:
+    """Normalize one file input into a ``(field, filename, bytes, type)`` part."""
+    if isinstance(item, str):
+        with open(item, "rb") as fh:
+            content = fh.read()
+        return (field_name, os.path.basename(item), content, _DEFAULT_CONTENT_TYPE)
+
+    if isinstance(item, tuple):
+        if len(item) == 2:
+            filename, content = item
+            content_type = _DEFAULT_CONTENT_TYPE
+        elif len(item) == 3:
+            filename, content, content_type = item
+        else:
+            raise ValueError("file tuple must be (filename, content) or (filename, content, content_type)")
+        if isinstance(content, str):
+            content = content.encode("utf-8")
+        return (field_name, filename, content, content_type)
+
+    raise TypeError(f"unsupported file input: {type(item)!r}")
+
+
+def to_parts(items: FileInput | list[FileInput], field_name: str) -> list[FilePart]:
+    """Normalize one file or a list of files into parts under ``field_name``."""
+    if isinstance(items, list):
+        return [to_part(it, field_name) for it in items]
+    return [to_part(items, field_name)]

praixis-0.1.0/praixis/_http.py

@@ -0,0 +1,77 @@
+"""HTTP primitives shared by the sync and async transports.
+
+Keeping these in one place means the auth scheme and the request/response
+shapes are defined once and reused, so the two transports can never drift
+apart.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+from urllib.parse import quote
+
+
+def encode_path_segment(value: str) -> str:
+    """Percent-encode a single URL path segment (filename, session id, ...).
+
+    Uses ``safe=""`` so reserved characters - spaces, ``/``, ``?``, ``#``, ``%``
+    - in a value like a filename can't corrupt the URL. Values already limited to
+    ``[A-Za-z0-9_.-]`` (collection names, the usual ids) pass through unchanged.
+    """
+    return quote(str(value), safe="")
+
+# A single file part: (field_name, filename, content_bytes, content_type).
+FilePart = tuple[str, str, bytes, str]
+# A single form field: (field_name, value).
+FormField = tuple[str, str]
+
+
+def auth_headers(api_key: str) -> dict[str, str]:
+    """Build the auth headers for a request.
+
+    Every app endpoint (chat + RAG) authenticates with the app-level
+    ``X-API-Key`` header. (Admin routes use HTTP Basic and a browser UI; they're
+    deliberately out of scope for this SDK.)
+    """
+    return {"X-API-Key": api_key} if api_key else {}
+
+
+# A streamed (text/event-stream) line of the form ``[KEY:value]``. The server
+# prefixes its streamed chat / RAG / summary responses with these marker lines
+# (e.g. [SESSION_ID:...], [SEARCH_QUERY:...], [SOURCES:a,b], [FILE:...],
+# [PROGRESS:...], [ERROR:...]) before emitting the generated text.
+_MARKER_RE = re.compile(r"^\[([A-Z_]+):(.*)\]$")
+
+
+def parse_event_stream(text: str) -> dict[str, Any]:
+    """Parse a buffered ``text/event-stream`` body into markers + generated text.
+
+    The chat, RAG-ask and file-summary endpoints don't return JSON - they stream
+    plain text whose leading lines are ``[KEY:value]`` markers followed by the
+    model's output. Both transports buffer that body and hand it here so the two
+    clients shape streamed responses identically.
+
+    Returns a dict with the recognised markers (``session_id``, ``search_query``,
+    ``sources`` as a list, ``file``), the joined generated ``text``, and the raw
+    ``markers`` map for anything else (e.g. ``PROGRESS``/``ERROR``).
+    """
+    markers: dict[str, str] = {}
+    body_lines: list[str] = []
+    for line in text.split("\n"):
+        m = _MARKER_RE.match(line)
+        if m:
+            markers[m.group(1)] = m.group(2)
+        else:
+            body_lines.append(line)
+
+    sources_raw = markers.get("SOURCES")
+    sources = [s for s in sources_raw.split(",") if s] if sources_raw is not None else None
+    return {
+        "session_id": markers.get("SESSION_ID"),
+        "search_query": markers.get("SEARCH_QUERY"),
+        "sources": sources,
+        "file": markers.get("FILE"),
+        "text": "\n".join(body_lines).strip("\n"),
+        "markers": markers,
+    }