semantic-python 0.1.0a1__tar.gz

semantic_python-0.1.0a1/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e '.[dev]'
+      - run: pytest --cov=semantic_python --cov-report=term-missing
+
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e '.[dev]'
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: mypy
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - name: Reject private or workspace-only files in the source archive
+        run: |
+          if tar -tf dist/*.tar.gz | grep -E '/(AGENTS|REQUIREMENTS)\.md$|/\.vscode/|/\.ipynb_checkpoints/'; then
+            echo "Source distribution contains a private or workspace-only file."
+            exit 1
+          fi
+      - name: Verify clean wheel installation and offline examples
+        run: |
+          python -m venv /tmp/semantic-python-clean
+          /tmp/semantic-python-clean/bin/python -m pip install --no-deps dist/*.whl
+          cd /tmp
+          /tmp/semantic-python-clean/bin/python "$GITHUB_WORKSPACE/examples/stop_loop.py"
+          /tmp/semantic-python-clean/bin/python "$GITHUB_WORKSPACE/examples/ticket_routing.py"
+          /tmp/semantic-python-clean/bin/python "$GITHUB_WORKSPACE/examples/escalation.py"

semantic_python-0.1.0a1/.github/workflows/release.yml

@@ -0,0 +1,38 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: python -m pip install --upgrade pip build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

semantic_python-0.1.0a1/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+.vscode/
+.ipynb_checkpoints/
+build/
+dist/
+htmlcov/
+.DS_Store
+.env
+.env.*
+!.env.example
+decisions.jsonl

semantic_python-0.1.0a1/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes will be documented here.
+
+## [0.1.0a1] - 2026-10-07
+
+### Added
+
+- Initial experimental `Semantic[str]` runtime.
+- Inspectable, bool-coercible decisions with explicit uncertainty handling.
+- Deterministic fake backend, caching, and offline record/replay support.
+- Experimental Laya 0.4 and OpenAI backend adapters with explicit data-egress
+  documentation.
+- Polished offline examples and opt-in OpenAI notebooks.
+- Python 3.10 through 3.13 testing, strict typing, and release artifact validation.
+
+### Security
+
+- Raw semantic state is excluded from decision recordings.
+- Hosted credentials are loaded from environment or secure runtime configuration.

semantic_python-0.1.0a1/CONTRIBUTING.md

@@ -0,0 +1,26 @@
+# Contributing
+
+Semantic Python is experimental. Open an issue before proposing changes to public semantics.
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[dev]'
+pytest
+ruff check .
+ruff format --check .
+mypy
+python -m build
+```
+
+Keep changes small, add offline tests for behavioral changes, and never require paid credentials in the default test suite. Live provider tests must be explicitly opted into.
+
+## Design changes
+
+Changes to equality, truthiness, uncertainty, privacy, or backend behavior need a written rationale and documentation. Ordinary non-semantic Python behavior must remain untouched.
+
+## Security and privacy
+
+Do not commit credentials or fixtures containing private user input. Prefer hashed or redacted state in logs and bug reports.

semantic_python-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Semantic Python contributors
+
+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.

semantic_python-0.1.0a1/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.5
+Name: semantic-python
+Version: 0.1.0a1
+Summary: Experimental semantic values for Python
+Project-URL: Homepage, https://github.com/SaiRiteshThela/semantic-python
+Project-URL: Repository, https://github.com/SaiRiteshThela/semantic-python
+Project-URL: Issues, https://github.com/SaiRiteshThela/semantic-python/issues
+Project-URL: Changelog, https://github.com/SaiRiteshThela/semantic-python/blob/main/CHANGELOG.md
+Author: Sai Ritesh Thela
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,decision-models,python,semantic
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: License :: OSI Approved :: MIT License
+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: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: twine>=6.0; extra == 'dev'
+Provides-Extra: laya
+Requires-Dist: laya<0.5,>=0.4.0; extra == 'laya'
+Provides-Extra: notebook
+Requires-Dist: ipykernel>=6.29; extra == 'notebook'
+Provides-Extra: openai
+Requires-Dist: openai<3,>=2; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# Semantic Python
+
+> Python, but `==` can understand meaning.
+
+Semantic Python is not a model like Laya or Jev. It is an opt-in Python value
+layer that turns backend inference into inspectable decisions for normal Python
+control flow. Only `Semantic(...)` values can invoke a model.
+
+## Install
+
+```bash
+python -m pip install 'semantic-python[openai]'
+export OPENAI_API_KEY="..."
+```
+
+## Demo
+
+Use natural-language intent in ordinary loops and async code:
+
+`functions` · `if` · `try/except` · `for` · `while` · `comprehensions` ·
+`generators` · `classes` · `with` · `async/await`
+
+```python
+import asyncio
+
+from semantic_python import (
+    OpenAIBackend,
+    Semantic,
+    UncertainDecisionError,
+    configure,
+)
+
+STOP = "the user wants to stop"
+
+configure(
+    backend=OpenAIBackend(model="gpt-6-luna"),
+    true_threshold=0.85,
+    false_threshold=0.15,
+    uncertainty="raise",
+)
+
+
+def decide(text: str):
+    return Semantic(text) == STOP
+
+
+messages = [
+    "Continue with the next ticket.",
+    "Save the work and close this session.",
+]
+
+for text in messages:
+    decision = decide(text)
+    print(f"stop={decision.value} p={decision.probability:.2f} model={decision.model}")
+
+    try:
+        if decision:
+            print("Stop requested")
+            break
+    except UncertainDecisionError:
+        print("Send to human review")
+
+
+async def decide_async(text: str):
+    return await asyncio.to_thread(decide, text)
+
+
+async_result = asyncio.run(decide_async(text))
+opposite = Semantic(text) != STOP
+
+print("async cache hit:", async_result.cached)
+print("negated:", opposite.value, opposite.probability)
+```
+
+The comparison returns a bool-coercible `Decision`, so `if` and loops work
+normally while probability, model provenance, caching, and replay remain
+available. `!=` negates the same judgment instead of issuing a second inference.
+
+## More Python patterns
+
+These examples continue with the configured backend and `STOP` proposition from
+the main demo.
+
+### `while`
+
+```python
+queue = iter(["Keep going", "Not yet", "Finished for today"])
+message = Semantic(next(queue))
+
+while message != STOP:
+    print("Processing:", message.value)
+    message = Semantic(next(queue))
+```
+
+### Comprehensions and generators
+
+```python
+texts = ["Continue", "Pause here", "That is all for today"]
+decisions = {text: decide(text) for text in texts}
+
+stop_requests = [text for text, decision in decisions.items() if decision.value]
+
+probabilities = (decision.probability for decision in decisions.values())
+print(stop_requests, list(probabilities))
+```
+
+### Classes
+
+```python
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class IntentRule:
+    proposition: str
+
+    def evaluate(self, text: str):
+        return Semantic(text) == self.proposition
+
+
+stop_rule = IntentRule("the user wants to stop")
+decision = stop_rule.evaluate("Please close the session")
+print(decision.value, decision.probability)
+```
+
+### Context managers and offline tests
+
+```python
+from semantic_python import FakeBackend, configuration
+
+state = "I'm done"
+fixtures = {(state, STOP): (True, 0.99)}
+
+with configuration(backend=FakeBackend(fixtures), cache=False):
+    assert Semantic(state) == STOP
+```
+
+## Backends
+
+Application code stays the same when the configured backend changes.
+
+| Backend | Install | Purpose |
+| --- | --- | --- |
+| `OpenAIBackend` | `semantic-python[openai]` | Hosted inference |
+| `LayaBackend` | `semantic-python[laya]` | Local inference |
+| `FakeBackend` | Included | Deterministic offline tests |
+
+OpenAI receives the wrapped state and proposition. Laya may download model
+checkpoints on first use. FakeBackend performs no network requests.
+
+## Semantics
+
+| Expression | Result |
+| --- | --- |
+| `plain_string == other` | Ordinary Python equality |
+| `Semantic(text) == proposition` | Inspectable semantic `Decision` |
+| `Semantic(text) != proposition` | Negated cached judgment |
+| `semantic is other` | Ordinary Python identity |
+| `Semantic(...) == Semantic(...)` | Rejected as ambiguous |
+| `hash(Semantic(...))` | Rejected; inference is never used for hashing |
+
+Probabilities at or above `0.85` resolve true, probabilities at or below `0.15`
+resolve false, and the default policy raises `UncertainDecisionError` between
+those thresholds. Backend failures are raised rather than converted to `False`.
+
+## Examples
+
+- [OpenAI demo](examples/semantic_python_demo.ipynb)
+- [Python control-flow demo](examples/python_primitives_demo.ipynb)
+- [Stop loop](examples/stop_loop.py)
+- [Ticket routing](examples/ticket_routing.py)
+- [Uncertainty and escalation](examples/escalation.py)
+
+The offline examples run without credentials:
+
+```bash
+python -m pip install -e .
+python examples/stop_loop.py
+python examples/ticket_routing.py
+python examples/escalation.py
+```
+
+## Safety
+
+- Model probability is an estimate, not truth or authorization.
+- Hosted inference can transmit sensitive text and incur cost.
+- Consequential actions should use conservative thresholds and human review.
+
+See [semantics](docs/semantics.md), [backends](docs/backends.md), and
+[uncertainty](docs/uncertainty.md) for the complete behavior.
+
+MIT licensed. Experimental and pre-alpha.

semantic_python-0.1.0a1/README.md

@@ -0,0 +1,192 @@
+# Semantic Python
+
+> Python, but `==` can understand meaning.
+
+Semantic Python is not a model like Laya or Jev. It is an opt-in Python value
+layer that turns backend inference into inspectable decisions for normal Python
+control flow. Only `Semantic(...)` values can invoke a model.
+
+## Install
+
+```bash
+python -m pip install 'semantic-python[openai]'
+export OPENAI_API_KEY="..."
+```
+
+## Demo
+
+Use natural-language intent in ordinary loops and async code:
+
+`functions` · `if` · `try/except` · `for` · `while` · `comprehensions` ·
+`generators` · `classes` · `with` · `async/await`
+
+```python
+import asyncio
+
+from semantic_python import (
+    OpenAIBackend,
+    Semantic,
+    UncertainDecisionError,
+    configure,
+)
+
+STOP = "the user wants to stop"
+
+configure(
+    backend=OpenAIBackend(model="gpt-6-luna"),
+    true_threshold=0.85,
+    false_threshold=0.15,
+    uncertainty="raise",
+)
+
+
+def decide(text: str):
+    return Semantic(text) == STOP
+
+
+messages = [
+    "Continue with the next ticket.",
+    "Save the work and close this session.",
+]
+
+for text in messages:
+    decision = decide(text)
+    print(f"stop={decision.value} p={decision.probability:.2f} model={decision.model}")
+
+    try:
+        if decision:
+            print("Stop requested")
+            break
+    except UncertainDecisionError:
+        print("Send to human review")
+
+
+async def decide_async(text: str):
+    return await asyncio.to_thread(decide, text)
+
+
+async_result = asyncio.run(decide_async(text))
+opposite = Semantic(text) != STOP
+
+print("async cache hit:", async_result.cached)
+print("negated:", opposite.value, opposite.probability)
+```
+
+The comparison returns a bool-coercible `Decision`, so `if` and loops work
+normally while probability, model provenance, caching, and replay remain
+available. `!=` negates the same judgment instead of issuing a second inference.
+
+## More Python patterns
+
+These examples continue with the configured backend and `STOP` proposition from
+the main demo.
+
+### `while`
+
+```python
+queue = iter(["Keep going", "Not yet", "Finished for today"])
+message = Semantic(next(queue))
+
+while message != STOP:
+    print("Processing:", message.value)
+    message = Semantic(next(queue))
+```
+
+### Comprehensions and generators
+
+```python
+texts = ["Continue", "Pause here", "That is all for today"]
+decisions = {text: decide(text) for text in texts}
+
+stop_requests = [text for text, decision in decisions.items() if decision.value]
+
+probabilities = (decision.probability for decision in decisions.values())
+print(stop_requests, list(probabilities))
+```
+
+### Classes
+
+```python
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class IntentRule:
+    proposition: str
+
+    def evaluate(self, text: str):
+        return Semantic(text) == self.proposition
+
+
+stop_rule = IntentRule("the user wants to stop")
+decision = stop_rule.evaluate("Please close the session")
+print(decision.value, decision.probability)
+```
+
+### Context managers and offline tests
+
+```python
+from semantic_python import FakeBackend, configuration
+
+state = "I'm done"
+fixtures = {(state, STOP): (True, 0.99)}
+
+with configuration(backend=FakeBackend(fixtures), cache=False):
+    assert Semantic(state) == STOP
+```
+
+## Backends
+
+Application code stays the same when the configured backend changes.
+
+| Backend | Install | Purpose |
+| --- | --- | --- |
+| `OpenAIBackend` | `semantic-python[openai]` | Hosted inference |
+| `LayaBackend` | `semantic-python[laya]` | Local inference |
+| `FakeBackend` | Included | Deterministic offline tests |
+
+OpenAI receives the wrapped state and proposition. Laya may download model
+checkpoints on first use. FakeBackend performs no network requests.
+
+## Semantics
+
+| Expression | Result |
+| --- | --- |
+| `plain_string == other` | Ordinary Python equality |
+| `Semantic(text) == proposition` | Inspectable semantic `Decision` |
+| `Semantic(text) != proposition` | Negated cached judgment |
+| `semantic is other` | Ordinary Python identity |
+| `Semantic(...) == Semantic(...)` | Rejected as ambiguous |
+| `hash(Semantic(...))` | Rejected; inference is never used for hashing |
+
+Probabilities at or above `0.85` resolve true, probabilities at or below `0.15`
+resolve false, and the default policy raises `UncertainDecisionError` between
+those thresholds. Backend failures are raised rather than converted to `False`.
+
+## Examples
+
+- [OpenAI demo](examples/semantic_python_demo.ipynb)
+- [Python control-flow demo](examples/python_primitives_demo.ipynb)
+- [Stop loop](examples/stop_loop.py)
+- [Ticket routing](examples/ticket_routing.py)
+- [Uncertainty and escalation](examples/escalation.py)
+
+The offline examples run without credentials:
+
+```bash
+python -m pip install -e .
+python examples/stop_loop.py
+python examples/ticket_routing.py
+python examples/escalation.py
+```
+
+## Safety
+
+- Model probability is an estimate, not truth or authorization.
+- Hosted inference can transmit sensitive text and incur cost.
+- Consequential actions should use conservative thresholds and human review.
+
+See [semantics](docs/semantics.md), [backends](docs/backends.md), and
+[uncertainty](docs/uncertainty.md) for the complete behavior.
+
+MIT licensed. Experimental and pre-alpha.

semantic_python-0.1.0a1/SECURITY.md

@@ -0,0 +1,10 @@
+# Security Policy
+
+This pre-alpha project is not ready for high-impact authorization decisions or untrusted production workloads.
+
+Report suspected vulnerabilities through the repository's private security-advisory
+form. Do not open a public issue containing exploit details, credentials, or user
+data. If private reporting is unavailable, contact the package owner through the
+maintainer controls on PyPI before sharing technical details.
+
+Remote backends may transmit wrapped semantic state outside the process. Applications must disclose and configure that behavior explicitly. Never commit provider credentials; use environment-based or secure runtime configuration.

semantic_python-0.1.0a1/TODO.md

@@ -0,0 +1,14 @@
+# TODO
+
+## After v0.1
+
+- Evaluate and, if justified, add a Jev hosted-backend adapter.
+- Evaluate Kev as an additional local/self-hosted backend.
+- Evaluate AnyJev as a research adapter path.
+- Define a stable public custom-backend registration API.
+- Add configurable retry, timeout, and cost-budget controls for hosted providers.
+- Add cross-backend conformance tests and reproducible quality/calibration benchmarks.
+
+These items are deliberately outside v0.1. Laya remains the primary local backend,
+OpenAI remains an explicitly selected experimental hosted backend, and `FakeBackend`
+exists for deterministic offline development, examples, and tests.