prism-ai-core 0.1.0__tar.gz

prism_ai_core-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.parity/

prism_ai_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 TJ MIller
+
+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.

prism_ai_core-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.5
+Name: prism-ai-core
+Version: 0.1.0
+Summary: Python port of Prism — a unified API layer over LLM providers.
+Author: Particle Academy
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,llm,openai,prism
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# prism-ai-core
+
+A unified API layer over LLM providers — the Python port of
+[Prism](https://github.com/Particle-Academy/prism).
+
+Zero runtime dependencies. Python 3.10+.
+
+```python
+from prism import Prism
+
+response = (
+    Prism.text()
+    .using("openai", "gpt-4o")
+    .with_prompt("Who are you?")
+    .as_text()
+)
+
+print(response.text)
+```
+
+> **Working on this package?** Read **[`AGENTS.md`](AGENTS.md)** first — the boundary
+> this package has to hold, the gates that must be green, and the traps that have
+> already caught someone.
+> `@link AGENTS.md`
+
+## Scope
+
+**Every capability the reference has**, and three of its eighteen providers.
+That is the shape of the remaining drift: one axis, not two.
+
+- **Capabilities — all of them.** `text`, `structured`, `stream`, `embeddings`,
+  `images`, `moderation`, `audio` (`text_to_speech` and `speech_to_text`),
+  `files`, `batch`, `fim`. A user message carries images and documents, and each
+  provider spells them its own way.
+- **Providers — `anthropic`, `mistral`, `openai`.** The OpenAI provider speaks
+  the **Responses API**; Mistral brings the chat-completions shape, which is a
+  different wire format rather than a variant of it.
+
+Not in this port: **the tool-execution loop** — a response that finishes on tool
+calls is refused with `tool_loop_not_supported` rather than half-executed — and
+the fifteen providers the reference has and this one does not. An unsupported
+capability raises a coded error rather than a missing attribute.
+
+Not every capability reaches every provider, because not every provider has one.
+`images`, `moderation`, `text_to_speech`, `files` and `batch` are OpenAI-only
+here, and `fim` is Mistral-only because Mistral is the only provider that
+implements it at all — in the reference as well. See the envelope's port gaps
+register for which of those are work someone could do and which are facts about
+the provider.
+
+Two things this port has that the reference does not:
+
+- **Every failure carries a stable `code`** (`prism.ErrorCode`). The reference
+  identifies failures by an English sentence, which forces consumers to match on
+  prose. The prose here is explicitly not part of the contract; the code is.
+- **Every value object rebuilds.** `to_dict()` *and* `from_dict()`. The
+  reference can write its value objects and cannot read them back, a gap that
+  forced a downstream package to invent its own rehydration and ship a defect
+  with it.
+
+## Install
+
+```
+pip install prism-ai-core
+```
+
+The distribution is `prism-ai-core`; the package it installs is imported as
+`prism`. To track `main` instead:
+
+```
+pip install "git+https://github.com/Particle-Academy/prism-py"
+```
+
+**Do not `pip install prism-ai`. That name on PyPI is somebody else's package**
+— author `gwhite`, shipping a `prism_ai` module, unrelated to this project. It
+is not a squat to route around later: it publishes **the same version number**
+this port carries, so a pin of `prism-ai==0.1.0` resolves to the stranger's
+distribution with nothing to tell you apart.
+
+It is not inert either. It declares `httpx`, `requests` and `tqdm`, where this
+port declares none, and installing it has been reported ROLLING HTTPX BACK
+(0.28.1 → 0.25.2) and breaking an MCP client sharing the environment. pip prints
+that conflict as a warning *after* the words "Successfully installed", so a CI
+or otherwise non-interactive install reports success and the damage surfaces
+somewhere else entirely.
+
+Pin the git URL, and leave a comment where you pin it — this is the kind of line
+a later tidy-up "corrects" into a version specifier.
+
+Configuration comes from explicit constructor arguments, falling back to
+`OPENAI_API_KEY`, `OPENAI_URL`, `OPENAI_ORGANIZATION` and `OPENAI_PROJECT`. The
+HTTP transport is injectable, so nothing has to reach the network in a test:
+
+```python
+from prism import OpenAI, Prism
+
+pending = Prism.text().using("openai", "gpt-4o", {"transport": my_transport})
+```
+
+## Parity
+
+What this port must do is pinned by
+[**prism-parity**](https://github.com/Particle-Academy/prism-parity), not by this
+README. The corpus is the contract — the cases, the goldens, the per-language
+skips and the discrimination probes all live there, each with its own notes
+saying what it exists to catch. Restating them here would only give them a
+second copy to drift from.
+
+The corpus and its loader install as the `prism-conformance` package:
+
+```
+git clone https://github.com/Particle-Academy/prism-parity .parity
+pip install ./.parity/loaders/py
+```
+
+Install it **last**: a path install can be pruned by a later install step. The
+loader finds its fixtures by walking up from its own installed location, so
+nothing here ever resolves a path into a sibling checkout.
+
+Run every suite:
+
+```
+python conformance/runner.py
+```
+
+Or one suite, or under a probe:
+
+```
+python conformance/runner.py --suite openai-text-request
+python conformance/runner.py --probe omit-null-keys
+```
+
+stdout is JSON and nothing else; the corpus version, digest and root go to
+stderr on every run. Exit 0 when every case passed or skipped, 1 on a failure,
+2 when the corpus failed to load, 3 when the runner could not start.
+
+### Probes
+
+`conformance/mutations.py` implements each probe the corpus declares as an
+injected defect, and `tests/test_probes.py` asserts that every one fails
+*exactly* the set of case ids the corpus names — not a superset, not "at least
+one" — and that the faithful control fails nothing. That is what makes the
+conformance table a measurement rather than decoration.
+
+Nothing in `src/prism` knows any of this exists. A defect a port can switch on
+is a defect a port can ship, so the mutants are installed from outside, over the
+real library's output, and removed again.
+
+## Development
+
+`src/` layout, so install the package before running the tests:
+
+```
+python -m venv .venv
+.venv/Scripts/python -m pip install -e ".[dev]"
+.venv/Scripts/python -m pip install ../prism-parity/loaders/py
+
+python -m pytest
+python -m mypy --strict
+python -m ruff check .
+python -m ruff format --check .
+```
+
+Set `PRISM_CORPUS_ROOT` to run the conformance tests against a parity checkout
+whose loader copy has not been re-synced yet. Unset — the normal case — the
+loader discovers its own fixtures.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

prism_ai_core-0.1.0/README.md

@@ -0,0 +1,170 @@
+# prism-ai-core
+
+A unified API layer over LLM providers — the Python port of
+[Prism](https://github.com/Particle-Academy/prism).
+
+Zero runtime dependencies. Python 3.10+.
+
+```python
+from prism import Prism
+
+response = (
+    Prism.text()
+    .using("openai", "gpt-4o")
+    .with_prompt("Who are you?")
+    .as_text()
+)
+
+print(response.text)
+```
+
+> **Working on this package?** Read **[`AGENTS.md`](AGENTS.md)** first — the boundary
+> this package has to hold, the gates that must be green, and the traps that have
+> already caught someone.
+> `@link AGENTS.md`
+
+## Scope
+
+**Every capability the reference has**, and three of its eighteen providers.
+That is the shape of the remaining drift: one axis, not two.
+
+- **Capabilities — all of them.** `text`, `structured`, `stream`, `embeddings`,
+  `images`, `moderation`, `audio` (`text_to_speech` and `speech_to_text`),
+  `files`, `batch`, `fim`. A user message carries images and documents, and each
+  provider spells them its own way.
+- **Providers — `anthropic`, `mistral`, `openai`.** The OpenAI provider speaks
+  the **Responses API**; Mistral brings the chat-completions shape, which is a
+  different wire format rather than a variant of it.
+
+Not in this port: **the tool-execution loop** — a response that finishes on tool
+calls is refused with `tool_loop_not_supported` rather than half-executed — and
+the fifteen providers the reference has and this one does not. An unsupported
+capability raises a coded error rather than a missing attribute.
+
+Not every capability reaches every provider, because not every provider has one.
+`images`, `moderation`, `text_to_speech`, `files` and `batch` are OpenAI-only
+here, and `fim` is Mistral-only because Mistral is the only provider that
+implements it at all — in the reference as well. See the envelope's port gaps
+register for which of those are work someone could do and which are facts about
+the provider.
+
+Two things this port has that the reference does not:
+
+- **Every failure carries a stable `code`** (`prism.ErrorCode`). The reference
+  identifies failures by an English sentence, which forces consumers to match on
+  prose. The prose here is explicitly not part of the contract; the code is.
+- **Every value object rebuilds.** `to_dict()` *and* `from_dict()`. The
+  reference can write its value objects and cannot read them back, a gap that
+  forced a downstream package to invent its own rehydration and ship a defect
+  with it.
+
+## Install
+
+```
+pip install prism-ai-core
+```
+
+The distribution is `prism-ai-core`; the package it installs is imported as
+`prism`. To track `main` instead:
+
+```
+pip install "git+https://github.com/Particle-Academy/prism-py"
+```
+
+**Do not `pip install prism-ai`. That name on PyPI is somebody else's package**
+— author `gwhite`, shipping a `prism_ai` module, unrelated to this project. It
+is not a squat to route around later: it publishes **the same version number**
+this port carries, so a pin of `prism-ai==0.1.0` resolves to the stranger's
+distribution with nothing to tell you apart.
+
+It is not inert either. It declares `httpx`, `requests` and `tqdm`, where this
+port declares none, and installing it has been reported ROLLING HTTPX BACK
+(0.28.1 → 0.25.2) and breaking an MCP client sharing the environment. pip prints
+that conflict as a warning *after* the words "Successfully installed", so a CI
+or otherwise non-interactive install reports success and the damage surfaces
+somewhere else entirely.
+
+Pin the git URL, and leave a comment where you pin it — this is the kind of line
+a later tidy-up "corrects" into a version specifier.
+
+Configuration comes from explicit constructor arguments, falling back to
+`OPENAI_API_KEY`, `OPENAI_URL`, `OPENAI_ORGANIZATION` and `OPENAI_PROJECT`. The
+HTTP transport is injectable, so nothing has to reach the network in a test:
+
+```python
+from prism import OpenAI, Prism
+
+pending = Prism.text().using("openai", "gpt-4o", {"transport": my_transport})
+```
+
+## Parity
+
+What this port must do is pinned by
+[**prism-parity**](https://github.com/Particle-Academy/prism-parity), not by this
+README. The corpus is the contract — the cases, the goldens, the per-language
+skips and the discrimination probes all live there, each with its own notes
+saying what it exists to catch. Restating them here would only give them a
+second copy to drift from.
+
+The corpus and its loader install as the `prism-conformance` package:
+
+```
+git clone https://github.com/Particle-Academy/prism-parity .parity
+pip install ./.parity/loaders/py
+```
+
+Install it **last**: a path install can be pruned by a later install step. The
+loader finds its fixtures by walking up from its own installed location, so
+nothing here ever resolves a path into a sibling checkout.
+
+Run every suite:
+
+```
+python conformance/runner.py
+```
+
+Or one suite, or under a probe:
+
+```
+python conformance/runner.py --suite openai-text-request
+python conformance/runner.py --probe omit-null-keys
+```
+
+stdout is JSON and nothing else; the corpus version, digest and root go to
+stderr on every run. Exit 0 when every case passed or skipped, 1 on a failure,
+2 when the corpus failed to load, 3 when the runner could not start.
+
+### Probes
+
+`conformance/mutations.py` implements each probe the corpus declares as an
+injected defect, and `tests/test_probes.py` asserts that every one fails
+*exactly* the set of case ids the corpus names — not a superset, not "at least
+one" — and that the faithful control fails nothing. That is what makes the
+conformance table a measurement rather than decoration.
+
+Nothing in `src/prism` knows any of this exists. A defect a port can switch on
+is a defect a port can ship, so the mutants are installed from outside, over the
+real library's output, and removed again.
+
+## Development
+
+`src/` layout, so install the package before running the tests:
+
+```
+python -m venv .venv
+.venv/Scripts/python -m pip install -e ".[dev]"
+.venv/Scripts/python -m pip install ../prism-parity/loaders/py
+
+python -m pytest
+python -m mypy --strict
+python -m ruff check .
+python -m ruff format --check .
+```
+
+Set `PRISM_CORPUS_ROOT` to run the conformance tests against a parity checkout
+whose loader copy has not been re-synced yet. Unset — the normal case — the
+loader discovers its own fixtures.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

prism_ai_core-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "prism-ai-core"
+version = "0.1.0"
+description = "Python port of Prism — a unified API layer over LLM providers."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Particle Academy" }]
+keywords = ["llm", "openai", "prism", "ai"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "mypy>=1.11", "ruff>=0.6"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/prism"]
+
+# The source archive carries the package and its licence, and nothing else: not the Lab's
+# loopback agent, CI workflows or contributor notes. Anchored with a leading slash, since an
+# unanchored README.md also matches agent/README.md.
+[tool.hatch.build.targets.sdist]
+include = ["/src/prism", "/README.md", "/LICENSE", "/pyproject.toml"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "conformance", "tests"]
+# Prose, not source. Ruff would collapse the README's chained-builder examples
+# onto one line, which is exactly the shape they exist to show.
+extend-exclude = ["*.md"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "N", "RUF"]
+ignore = [
+    # `Tool.format` / schema `format` mirror the reference field names.
+    "A003",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["E501"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src", "conformance", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# `-ra` so skips and their reasons are always printed. A skip nobody sees is a
+# suite that quietly shrank.
+addopts = "-q -ra"
+# The conformance runner is test support outside src/, and the tests import it.
+pythonpath = ["."]

prism_ai_core-0.1.0/src/prism/__init__.py

@@ -0,0 +1,181 @@
+"""prism — a unified API layer over LLM providers.
+
+This is the Python port of Prism:
+
+>>> from prism import Prism
+>>> response = (                             # doctest: +SKIP
+...     Prism.text()
+...     .using("openai", "gpt-4o")
+...     .with_prompt("Who are you?")
+...     .as_text()
+... )
+"""
+
+from __future__ import annotations
+
+from prism import canonical
+from prism.audio import (
+    AudioPendingRequest,
+    AudioResponse,
+    AudioTextResponse,
+    SpeechToTextRequest,
+    TextToSpeechRequest,
+)
+from prism.batch import (
+    BatchJob,
+    BatchJobError,
+    BatchJobRequestCounts,
+    BatchListResult,
+    BatchPendingRequest,
+    BatchRequest,
+    BatchRequestItem,
+    BatchResultItem,
+    BatchResultStatus,
+    BatchStatus,
+    CancelBatchRequest,
+    GetBatchResultsRequest,
+    ListBatchesRequest,
+    RetrieveBatchRequest,
+)
+from prism.canonical import encode as canonical_encode
+from prism.enums import FinishReason, ToolChoice
+from prism.enums import Provider as ProviderName
+from prism.errors import ErrorCode, PrismError
+from prism.files import (
+    DeleteFileRequest,
+    DeleteFileResult,
+    DownloadFileRequest,
+    FileData,
+    FileListResult,
+    FilesPendingRequest,
+    GetFileMetadataRequest,
+    ListFilesRequest,
+    UploadFileRequest,
+)
+from prism.fim import FimPendingRequest, FimRequest, FimResponse
+from prism.http import (
+    HttpRequest,
+    HttpResponse,
+    MultipartBody,
+    MultipartFile,
+    Transport,
+    UrllibTransport,
+    encode_multipart,
+)
+from prism.prism import Prism
+from prism.providers.base import Provider
+from prism.providers.mistral import Mistral, MistralStreamMapper
+from prism.providers.openai import OpenAI, build_request_body, build_tools, parse_text_response
+from prism.registry import register_provider, resolve_provider
+from prism.schema import BooleanSchema, NumberSchema, Schema, StringSchema
+from prism.text import PendingRequest, Request, Response, ResponseBuilder, Step
+from prism.tool import Tool
+from prism.value_objects import (
+    AssistantMessage,
+    Message,
+    Meta,
+    ProviderRateLimit,
+    ProviderTool,
+    ProviderToolCall,
+    SystemMessage,
+    Text,
+    ToolCall,
+    ToolResult,
+    ToolResultMessage,
+    Usage,
+    UserMessage,
+    message_from_dict,
+)
+from prism.value_objects.generated_audio import GeneratedAudio
+from prism.value_objects.media_file import Audio, Document, Image, Media, Video
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AssistantMessage",
+    "Audio",
+    "AudioPendingRequest",
+    "AudioResponse",
+    "AudioTextResponse",
+    "BatchJob",
+    "BatchJobError",
+    "BatchJobRequestCounts",
+    "BatchListResult",
+    "BatchPendingRequest",
+    "BatchRequest",
+    "BatchRequestItem",
+    "BatchResultItem",
+    "BatchResultStatus",
+    "BatchStatus",
+    "BooleanSchema",
+    "CancelBatchRequest",
+    "DeleteFileRequest",
+    "DeleteFileResult",
+    "Document",
+    "DownloadFileRequest",
+    "ErrorCode",
+    "FileData",
+    "FileListResult",
+    "FilesPendingRequest",
+    "FimPendingRequest",
+    "FimRequest",
+    "FimResponse",
+    "FinishReason",
+    "GeneratedAudio",
+    "GetBatchResultsRequest",
+    "GetFileMetadataRequest",
+    "HttpRequest",
+    "HttpResponse",
+    "Image",
+    "ListBatchesRequest",
+    "ListFilesRequest",
+    "Media",
+    "Message",
+    "Meta",
+    "Mistral",
+    "MistralStreamMapper",
+    "MultipartBody",
+    "MultipartFile",
+    "NumberSchema",
+    "OpenAI",
+    "PendingRequest",
+    "Prism",
+    "PrismError",
+    "Provider",
+    "ProviderName",
+    "ProviderRateLimit",
+    "ProviderTool",
+    "ProviderToolCall",
+    "Request",
+    "Response",
+    "ResponseBuilder",
+    "RetrieveBatchRequest",
+    "Schema",
+    "SpeechToTextRequest",
+    "Step",
+    "StringSchema",
+    "SystemMessage",
+    "Text",
+    "TextToSpeechRequest",
+    "Tool",
+    "ToolCall",
+    "ToolChoice",
+    "ToolResult",
+    "ToolResultMessage",
+    "Transport",
+    "UploadFileRequest",
+    "UrllibTransport",
+    "Usage",
+    "UserMessage",
+    "Video",
+    "__version__",
+    "build_request_body",
+    "build_tools",
+    "canonical",
+    "canonical_encode",
+    "encode_multipart",
+    "message_from_dict",
+    "parse_text_response",
+    "register_provider",
+    "resolve_provider",
+]