warm-sdk 0.1.3__py3-none-any.whl

warm_sdk-0.1.3.dist-info/METADATA

@@ -0,0 +1,207 @@
+Metadata-Version: 2.5
+Name: warm-sdk
+Version: 0.1.3
+Summary: HTTP client and agent-framework adapters for a WritersLogic Adaptive Retention & Memory service
+Project-URL: Homepage, https://writerslogic.com/warm/
+Project-URL: Documentation, https://writerslogic.com/warm/docs/
+Project-URL: Repository, https://github.com/writerslogic/warm
+Author-email: WritersLogic <david@writerslogic.com>
+License: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: sniffio>=1.3
+Provides-Extra: all
+Requires-Dist: crewai>=0.28.0; extra == 'all'
+Requires-Dist: dspy-ai>=2.4.0; extra == 'all'
+Requires-Dist: embedchain>=0.1.114; extra == 'all'
+Requires-Dist: haystack-ai>=2.0.0; extra == 'all'
+Requires-Dist: langchain-core>=0.1.0; extra == 'all'
+Requires-Dist: llama-index-core>=0.10.0; extra == 'all'
+Requires-Dist: phidata>=2.4.0; extra == 'all'
+Requires-Dist: pydantic-ai>=0.0.14; extra == 'all'
+Requires-Dist: semantic-kernel>=1.39.4; extra == 'all'
+Requires-Dist: smolagents>=1.0.0; extra == 'all'
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.28.0; extra == 'crewai'
+Provides-Extra: dspy
+Requires-Dist: dspy-ai>=2.4.0; extra == 'dspy'
+Provides-Extra: embedchain
+Requires-Dist: embedchain>=0.1.114; extra == 'embedchain'
+Provides-Extra: fast
+Requires-Dist: orjson>=3.9; extra == 'fast'
+Provides-Extra: haystack
+Requires-Dist: haystack-ai>=2.0.0; extra == 'haystack'
+Provides-Extra: import-annoy
+Requires-Dist: annoy>=1.17; extra == 'import-annoy'
+Requires-Dist: numpy>=1.26; extra == 'import-annoy'
+Provides-Extra: import-chroma
+Requires-Dist: chromadb>=0.5; extra == 'import-chroma'
+Provides-Extra: import-faiss
+Requires-Dist: faiss-cpu>=1.8; extra == 'import-faiss'
+Requires-Dist: numpy>=1.26; extra == 'import-faiss'
+Provides-Extra: import-files
+Requires-Dist: duckdb>=1.0; extra == 'import-files'
+Requires-Dist: numpy>=1.26; extra == 'import-files'
+Requires-Dist: pyarrow>=15; extra == 'import-files'
+Provides-Extra: import-hnswlib
+Requires-Dist: hnswlib>=0.8; extra == 'import-hnswlib'
+Requires-Dist: numpy>=1.26; extra == 'import-hnswlib'
+Provides-Extra: import-lancedb
+Requires-Dist: lancedb>=0.9; extra == 'import-lancedb'
+Requires-Dist: pyarrow>=15; extra == 'import-lancedb'
+Provides-Extra: import-langchain
+Requires-Dist: faiss-cpu>=1.8; extra == 'import-langchain'
+Requires-Dist: langchain-core>=0.2; extra == 'import-langchain'
+Provides-Extra: import-letta
+Requires-Dist: letta-client>=0.1; extra == 'import-letta'
+Provides-Extra: import-llamaindex
+Requires-Dist: llama-index-core>=0.10; extra == 'import-llamaindex'
+Provides-Extra: import-mem0
+Requires-Dist: mem0ai<0.2,>=0.1; extra == 'import-mem0'
+Provides-Extra: import-milvus
+Requires-Dist: pymilvus>=2.4; extra == 'import-milvus'
+Provides-Extra: import-mongodb
+Requires-Dist: pymongo>=4.6; extra == 'import-mongodb'
+Provides-Extra: import-openai
+Requires-Dist: openai>=1.40; extra == 'import-openai'
+Provides-Extra: import-pgvector
+Requires-Dist: psycopg[binary]>=3.1; extra == 'import-pgvector'
+Provides-Extra: import-pinecone
+Requires-Dist: pinecone>=5; extra == 'import-pinecone'
+Provides-Extra: import-qdrant
+Requires-Dist: qdrant-client>=1.9; extra == 'import-qdrant'
+Provides-Extra: import-redis
+Requires-Dist: redis>=5; extra == 'import-redis'
+Provides-Extra: import-sqlite-vec
+Requires-Dist: sqlite-vec>=0.1.1; extra == 'import-sqlite-vec'
+Provides-Extra: import-zep
+Requires-Dist: zep-cloud>=2; extra == 'import-zep'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == 'langchain'
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.10.0; extra == 'llamaindex'
+Provides-Extra: phidata
+Requires-Dist: phidata>=2.4.0; extra == 'phidata'
+Provides-Extra: pydantic-ai
+Requires-Dist: pydantic-ai>=0.0.14; extra == 'pydantic-ai'
+Provides-Extra: semantic-kernel
+Requires-Dist: semantic-kernel>=1.39.4; extra == 'semantic-kernel'
+Provides-Extra: smolagents
+Requires-Dist: smolagents>=1.0.0; extra == 'smolagents'
+Description-Content-Type: text/markdown
+
+<a href="https://writerslogic.com/warm/"><img src="https://raw.githubusercontent.com/writerslogic/warm/main/assets/crystal-halo/crystal-detailed-static.png" width="96" alt="WARM logo" align="left"></a>
+
+# WARM SDK
+
+Python HTTP client and framework adapters for a WARM service.
+
+[Website](https://writerslogic.com/warm/) · [Documentation](https://writerslogic.com/warm/docs/) · [Source](https://github.com/writerslogic/warm) · [License](https://github.com/writerslogic/warm/blob/main/LICENSE)
+
+<br clear="left">
+
+The client talks to `warm-server`, which ships in the WARM repository. The server
+stores vectors you supply and exposes document and query endpoints. See the
+[server guide](https://writerslogic.com/warm/docs/latest/SERVER/) to run it.
+
+## Installation
+
+```bash
+uv add warm-sdk
+```
+
+Framework adapters are optional extras. Install one, or all of them:
+
+```bash
+uv add "warm-sdk[langchain]"
+uv add "warm-sdk[all]"
+```
+
+The earlier standalone `langchain-holographic` distribution is retired. For LangChain, install
+`warm-sdk[langchain]` and import `WarmVectorStore` from
+`writerslogic_warm_sdk.langchain`. This adapter connects to `warm-server`; update the old
+`langchain_holographic` import and its local-store configuration when migrating.
+
+The `fast` extra adds `orjson` for request encoding, which cuts the per-query cost of sending an embedding:
+
+```bash
+uv add "warm-sdk[fast]"
+```
+
+Requires Python 3.10 or newer.
+
+## Quick Start
+
+```python
+from writerslogic_warm_sdk import WarmClient
+
+client = WarmClient(url="http://localhost:8080", api_key="...")
+
+client.add_documents([
+    {"id": "doc-1", "text": "Paris is the capital of France.", "vector": [0.12, -0.03, 0.88], "metadata": {"lang": "en"}},
+])
+
+response = client.query(query_vector=[0.10, -0.01, 0.90], top_k=3, filter={"lang": "en"})
+print(response["matches"])
+client.delete_document("doc-1")
+client.close()
+```
+
+`AsyncWarmClient` has the same methods as coroutines; close it with `await client.aclose()`. Embeddings come from your own model: the SDK sends vectors, it does not compute them.
+
+After bulk ingestion, `client.maintain_document_index()` explicitly builds the server's
+exact dense document index and returns `{"documentIndexTrained": true}` when the
+store is eligible. Smaller or unsupported stores return `false` and use exact scanning.
+Use `await client.maintain_document_index()` with the async client. Rebuild after updates
+or restart; the index is a runtime cache. Searches preserve the existing cosine results,
+and metadata filters continue to apply before ranking. This method requires an
+`warm-server` version exposing `POST /api/v1/index/maintain`.
+
+## Source Evidence
+
+`complete_evidence` packs complete source observations in your retrieval order. Each observation contains a turn handle, session handle, observation time, role, and verbatim text. Supply opaque caller IDs as lowercase SHA-256 hex handles, and keep their association with your original records.
+
+```python
+from hashlib import sha256
+from writerslogic_warm_sdk import complete_evidence, decode_source_packet
+
+def handle(identity):
+    return sha256(identity.encode("utf-8")).hexdigest()
+
+session = handle("session-7")
+candidates = [
+    [(handle("turn-1"), session, "2026-10-13T10:00:00Z", "user",
+      "I have two aquarium tanks.")],
+    [(handle("turn-2"), session, "2026-10-13T10:00:00Z", "assistant",
+      "You mentioned two aquarium tanks.")],
+]
+
+selection = complete_evidence(candidates, selected=[0], budget_bytes=2048)
+observations = decode_source_packet(selection.packet)
+assert observations == [candidates[index] for index in selection.selected]
+```
+
+The indices in `selected` are mandatory; packing raises `ValueError` if they exceed the budget. Additional complete groups fit in candidate order, with shared text and session metadata stored once. Decoding preserves every occurrence, role, observation time, and source text. The budget counts UTF-8 packet bytes; measure reader tokens separately. Packets contain source observations and no inferred answer or event date. These helpers run locally and make no service calls.
+
+## Integrations
+
+| Framework | Extra | Import |
+|-----------|-------|--------|
+| LangChain | `langchain` | `from writerslogic_warm_sdk.langchain import WarmVectorStore` |
+| LlamaIndex | `llamaindex` | `from writerslogic_warm_sdk.llamaindex import WarmVectorStore` |
+| Haystack | `haystack` | `from writerslogic_warm_sdk.haystack import WarmDocumentStore` |
+| Semantic Kernel | `semantic-kernel` | `from writerslogic_warm_sdk.semantic_kernel import WarmMemoryStore` |
+| DSPy | `dspy` | `from writerslogic_warm_sdk.dspy import WarmRM` |
+| CrewAI | `crewai` | `from writerslogic_warm_sdk.crewai import WarmSearchTool` |
+| Embedchain | `embedchain` | `from writerslogic_warm_sdk.embedchain import WarmDB` |
+| Phidata | `phidata` | `from writerslogic_warm_sdk.phidata import WarmVectorDb` |
+| Pydantic AI | `pydantic-ai` | `from writerslogic_warm_sdk.pydantic_ai import get_warm_tool` |
+| SmolAgents | `smolagents` | `from writerslogic_warm_sdk.smolagents import WarmSearchTool` |
+
+## Vector Masking
+
+Passing `zero_trust_key` masks every embedding client-side with a keyed signed permutation (`VectorMask`, scrypt-derived). The server can still rank vectors because inner products and cosine similarity are preserved exactly. This is obfuscation, **not encryption**: the server learns all pairwise similarities, and known plain/masked pairs reveal the key for the coordinates they cover. Pass a per-collection `mask_salt` (at least 16 bytes) shared by all clients of that collection. Masks produced by 0.1.0/0.1.1 are not compatible and were not secure.
+
+## License
+
+Apache-2.0. See the [LICENSE](https://github.com/writerslogic/warm/blob/main/LICENSE).

warm_sdk-0.1.3.dist-info/RECORD

@@ -0,0 +1,70 @@
+writerslogic_warm_sdk/__init__.py,sha256=F-9QymU9-vU4MrK7QqbPceAAVSyCxuTT27MMv8n7TNo,489
+writerslogic_warm_sdk/_transport.py,sha256=mXryLv1Ad9HpYxxBYEbD-UomDyXPSId5nWAt3MHRG78,4877
+writerslogic_warm_sdk/client.py,sha256=sFmZUHLI53DEG5eBotWp8NolrUgEHFFBVVhrflc8Qf4,10537
+writerslogic_warm_sdk/evidence.py,sha256=lT__Mxs8nQNT7vFbZVfDplnjivYHDX2eh6KBqJvQPjQ,9896
+writerslogic_warm_sdk/memory.py,sha256=s-Ewt9VnYRmKj-nY7UFoJXIix4N6vzhSus9v8bcNGdE,27445
+writerslogic_warm_sdk/memory.pyi,sha256=zzoSpvBeTobI9gZOtMH4D6t8UzmW7RVlrpSgLC2LfC4,7798
+writerslogic_warm_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+writerslogic_warm_sdk/crewai/__init__.py,sha256=uH8ejfkrKotkES9TL5uVoZt1znbNCmtWxOM3XXRSouU,140
+writerslogic_warm_sdk/crewai/tools.py,sha256=BAIqCf2Xa1maCLKoLO07HJ1ZTAMJhFqD3QJyo_JMHZU,1553
+writerslogic_warm_sdk/dspy/__init__.py,sha256=Y1XLmRhIFqFg3BfRWlujBTplxTeB8RiPO40uPpbD3BM,104
+writerslogic_warm_sdk/dspy/retriever.py,sha256=HQy1EqCnuSGMHS4jFF9elEghCDZPfXGZGNpELaz5IRQ,1425
+writerslogic_warm_sdk/embedchain/__init__.py,sha256=TYSIXCif4sRHMe4rpKXumcDrmwzM_mhNPqmrbCCcM2w,103
+writerslogic_warm_sdk/embedchain/vectordb.py,sha256=aSEwfWEcXoUL-_sgsFYWqpcYpmZ6S4jZ1HVByJIAxYs,1846
+writerslogic_warm_sdk/haystack/__init__.py,sha256=2u1HpQnc3NlefyKnA3PXRsN4KOaAIzEkrbkV2EBqZBo,164
+writerslogic_warm_sdk/haystack/document_store.py,sha256=unzBhOhFD2_gc78koDsLxcJtRhRedVpETqye8yILHmU,1351
+writerslogic_warm_sdk/importers/__init__.py,sha256=frLqXmUBsEz9JmZL1K6yhmfhbNXeKq-m1SQR7DSBLTs,1023
+writerslogic_warm_sdk/importers/checkpoint.py,sha256=xHyI41cXlthPkNLv4r1CjbFkoYX-z-L-CceFs4QGWGA,4085
+writerslogic_warm_sdk/importers/cli.py,sha256=dajPGc-D8ifoA1LFlaFotV_IbLXkWmgGSgznRZIPLXQ,10059
+writerslogic_warm_sdk/importers/common.py,sha256=X4vS76a2EQhFOp5jN00_g9h3p5g4YYJzc_9Cn1GTXh0,7475
+writerslogic_warm_sdk/importers/inventory.py,sha256=wphY4jlOPvPGKarhinwibsppm5buRVQrbpmwVziXoLI,5867
+writerslogic_warm_sdk/importers/mapping.py,sha256=CIHP9HNdPfVlmpXIsOSuoldhps0TFuOJ6FOSRDLHwDA,15833
+writerslogic_warm_sdk/importers/model.py,sha256=MxpWnrRFejSOI2oXCoG7lM3pPIoegp5_IR8cLas8WU4,2737
+writerslogic_warm_sdk/importers/options.py,sha256=b45AfRQlS5Jx2Mycas3UbJU2Ceuhd3drKgQdXloJqmg,5558
+writerslogic_warm_sdk/importers/pipeline.py,sha256=_XEIzb9SNxKxTvLWa00ElYHeWmNdNe68TK8m-k_omUw,14441
+writerslogic_warm_sdk/importers/report.py,sha256=TLzq7WlCE_782rbeT9E-ankEJYqxn_0GP7xNmD2a9j0,7130
+writerslogic_warm_sdk/importers/sink.py,sha256=Ci8ydS6xZl7KCqU8-GPLcLI2nR39BNtWzd2cQ9uVd68,10802
+writerslogic_warm_sdk/importers/verify.py,sha256=n6UPiBSXC9T_CNgVinQCyxtblt7OUvJUUeVrkHKk3I0,9902
+writerslogic_warm_sdk/importers/sources/__init__.py,sha256=UPb-nxwbF5DPy0Oq0oFay1st7cYs_JvOZWZvdc1iZEo,2209
+writerslogic_warm_sdk/importers/sources/_fields.py,sha256=ov_X5GFdOhS2ze-fHIExXrgYivu1IC7PHlyb7vyQwaY,3987
+writerslogic_warm_sdk/importers/sources/_sidecar.py,sha256=z9sM6bNTM7_NYCuMMxD560PEb1X29i7IBtyHlTZGFSY,4957
+writerslogic_warm_sdk/importers/sources/annoy.py,sha256=QMq6LcyTjWM5S9zYbY2CHJpl7qafEuQA40ZsSsMLSNw,4774
+writerslogic_warm_sdk/importers/sources/base.py,sha256=dAYNeKoqDjz5zuqZbQdfTV4AN10uCSmcWPp36cWMyKg,6123
+writerslogic_warm_sdk/importers/sources/chroma.py,sha256=XFas-eQtVXFRtl3heaRcWfStQw0HJD72GZPUvuj43lY,5645
+writerslogic_warm_sdk/importers/sources/elastic.py,sha256=kzN4Sebg8h32MLuTmFk6FnJ6WhDKZMtdFCp9uM-H9As,12119
+writerslogic_warm_sdk/importers/sources/faiss.py,sha256=xaG7nu-pKiiFtjZu3YMtN4pafJ3VSgp6wTOBUhg5KpE,7255
+writerslogic_warm_sdk/importers/sources/files.py,sha256=vzBJm2MIaHSXSrv9VM3M4qndW_riXfgnA8S3ltEzDYU,14613
+writerslogic_warm_sdk/importers/sources/hnswlib.py,sha256=0QgMz09Om8QOQJEOrH0xyaGTE0UIzx9BmfbjNCg9cRo,6331
+writerslogic_warm_sdk/importers/sources/lancedb.py,sha256=yht5yXrskDCh_glU7brCg3Ml6q9xq77zzArHGrsnpFA,5011
+writerslogic_warm_sdk/importers/sources/langchain.py,sha256=HUj5TdRRM6X5m-W7MJWvYVi6OfrFswJ1dcellV9E57s,9678
+writerslogic_warm_sdk/importers/sources/letta.py,sha256=Cmw_NIcb70fKqotOsNQymVyx1SgxPCH0TmWjwZs4pu0,7092
+writerslogic_warm_sdk/importers/sources/llamaindex.py,sha256=7xsgWJHKmBZLWtefKX6w6OWDiLiVR7Qa5x10F8kGev0,6721
+writerslogic_warm_sdk/importers/sources/markdown.py,sha256=xUMn7VldaLyRrQT_yj1EBk-SLtMSFXoGo2aPHr89rxc,8942
+writerslogic_warm_sdk/importers/sources/mem0.py,sha256=Cm9G_ANaDOGwhA8IiOJt0z74o6y2ZNGII7ImUNiIEpQ,14877
+writerslogic_warm_sdk/importers/sources/milvus.py,sha256=SMSY-iEy5OFo32Q6NK1rEAaOtoQ0R7X0cKNX4Rc18xU,9562
+writerslogic_warm_sdk/importers/sources/mongodb.py,sha256=d38ZsZ7xV_aOy3C_v9XYK5CrdOmpfmnpx7JKxwQhiCk,7154
+writerslogic_warm_sdk/importers/sources/openai_vs.py,sha256=kziGazhEHReOfwsHbK3o-lMBMOQU8gWV2aK_ymEYFBo,5529
+writerslogic_warm_sdk/importers/sources/pgvector.py,sha256=J8hodWJn9e5GOnS9Dq5iRcWnN-8QfYWHQ2KuAHrBalw,6278
+writerslogic_warm_sdk/importers/sources/pinecone.py,sha256=uMLrlUDVMhPLC4Mxd2AaLOKrzI4Ukw-cy3O9Xhc6Hpg,8810
+writerslogic_warm_sdk/importers/sources/qdrant.py,sha256=3xeaAheL5XHb3dLbnk2A0ei5NnDsISDzowB_Sd_aBdE,8055
+writerslogic_warm_sdk/importers/sources/redis.py,sha256=_YzATwkpczUDOxglRxVWsU6LJzx30-6krL3Do4PjihE,10450
+writerslogic_warm_sdk/importers/sources/sqlite_vec.py,sha256=MfXisCeCi0gaMjp4e77rZaoosnUCCxUNnmK0ZP3eJ8w,7112
+writerslogic_warm_sdk/importers/sources/vespa.py,sha256=swyU8B0iEofQzGoGQCQqvS5_Vm2f9uxl4HcwHQtEyyQ,11381
+writerslogic_warm_sdk/importers/sources/weaviate.py,sha256=PJnoQlj5_a8EOIzrSQL8iRSsKtrgICtorl70rOKn44w,8749
+writerslogic_warm_sdk/importers/sources/zep.py,sha256=jlIj9V-W-Quouf9e6NsXaMmAUIQeetZfD9sd8SF1qfE,7544
+writerslogic_warm_sdk/langchain/__init__.py,sha256=jRX6kZbFQbdEnO8eyhZV4ERwBjIhtu3iWGA8PaCe7FE,152
+writerslogic_warm_sdk/langchain/vectorstores.py,sha256=yYrWJvyBTDr-RYh6u91R0r8Qg1wOdoe2dC234YTc6lE,2290
+writerslogic_warm_sdk/llamaindex/__init__.py,sha256=jRX6kZbFQbdEnO8eyhZV4ERwBjIhtu3iWGA8PaCe7FE,152
+writerslogic_warm_sdk/llamaindex/vectorstores.py,sha256=PxgWvDeQVcXPIhTM5EOCa8iMTP5RXOkL56NxF42EFV0,2232
+writerslogic_warm_sdk/phidata/__init__.py,sha256=zS_KNdVKWN2v4cpUbjZrFqeSRKQAd-0KLRJ4VvmxVhw,133
+writerslogic_warm_sdk/phidata/vectordb.py,sha256=XG2Idqd8ZqwXzx-SrTRExQt2Vyg99_E8mbqjzxA8iNE,1998
+writerslogic_warm_sdk/pydantic_ai/__init__.py,sha256=KWf_yRn9Uk1zjBRnlVuk4Nd-ZxskM3zcNFnTZBNj44k,220
+writerslogic_warm_sdk/pydantic_ai/tools.py,sha256=1AkkJn0qwM1gSbNcq5gO4tEp4l0jUbh5ld-_O8fqSHc,1378
+writerslogic_warm_sdk/semantic_kernel/__init__.py,sha256=B6Y8_TMBbv0CjhxYy914TpEd995vJdGmxNwqda6VMDU,72
+writerslogic_warm_sdk/semantic_kernel/memory_store.py,sha256=jBwOmj4wjGvCWvsd6Gm-KMw3nw6_E9ordQC8OJ3aSJU,3511
+writerslogic_warm_sdk/smolagents/__init__.py,sha256=uH8ejfkrKotkES9TL5uVoZt1znbNCmtWxOM3XXRSouU,140
+writerslogic_warm_sdk/smolagents/tools.py,sha256=eZ5DfnAR3AwmLuJt_NHqE_oniFaqSqmISXKTz3bNGPQ,1673
+warm_sdk-0.1.3.dist-info/METADATA,sha256=pvqIx5HgyAYPT7i-nTzNNnp0mF5e6NzG3QvGswyqyBw,9724
+warm_sdk-0.1.3.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+warm_sdk-0.1.3.dist-info/entry_points.txt,sha256=HNtyKHRP7dGA9OGlhAWHeGXLWCpcRmi6LZMBNLDDZ6g,73
+warm_sdk-0.1.3.dist-info/RECORD,,

warm_sdk-0.1.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

warm_sdk-0.1.3.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+warm-import = writerslogic_warm_sdk.importers.cli:main

writerslogic_warm_sdk/__init__.py

@@ -0,0 +1,21 @@
+from .client import AsyncWarmClient, WarmClient, WarmError, VectorMask
+from .memory import AsyncMemoryClient, MemoryClient
+from .evidence import (
+    EvidenceSelection,
+    complete_evidence,
+    decode_source_packet,
+    encode_source_packet,
+)
+
+__all__ = [
+    "WarmClient",
+    "AsyncWarmClient",
+    "WarmError",
+    "VectorMask",
+    "MemoryClient",
+    "AsyncMemoryClient",
+    "EvidenceSelection",
+    "complete_evidence",
+    "decode_source_packet",
+    "encode_source_packet",
+]

writerslogic_warm_sdk/_transport.py

@@ -0,0 +1,118 @@
+"""Keep-alive HTTP/1.1 transport on ``http.client`` for plain-HTTP service URLs.
+
+httpx's default transport frames each request through httpcore and h11, which costs more per
+call on loopback than the server spends answering a vector query. This transport keeps one
+persistent ``http.client`` connection per thread and hands httpx a complete response, so the
+``httpx.Client`` API, its errors and its response objects stay the same.
+"""
+
+import http.client
+import os
+import select
+import socket
+import threading
+from typing import List, Optional
+
+import httpx
+
+_PROXY_VARS = ("http_proxy", "https_proxy", "all_proxy", "HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY")
+
+
+def usable_for(url: str) -> bool:
+    """True for a plain ``http`` URL with no proxy configured in the environment.
+
+    Passing any transport to ``httpx.Client`` turns off its environment proxies, so a URL that
+    a proxy variable could apply to keeps httpx's own transport.
+    """
+    return httpx.URL(url).scheme == "http" and not any(os.environ.get(v) for v in _PROXY_VARS)
+
+
+def _timeout(request: httpx.Request) -> Optional[float]:
+    timeout = request.extensions.get("timeout") or {}
+    values = [v for v in (timeout.get("connect"), timeout.get("read"), timeout.get("write")) if v is not None]
+    return max(values) if values else None
+
+
+def _stale(conn: http.client.HTTPConnection) -> bool:
+    """An idle keep-alive socket that is readable has been closed (or poisoned) by the peer."""
+    sock = conn.sock
+    if sock is None:
+        return False
+    try:
+        readable, _, _ = select.select([sock], [], [], 0)
+    except (OSError, ValueError):
+        return True
+    return bool(readable)
+
+
+class KeepAliveTransport(httpx.BaseTransport):
+    def __init__(self) -> None:
+        self._local = threading.local()
+        self._lock = threading.Lock()
+        self._conns: List[http.client.HTTPConnection] = []
+
+    def _connection(self, request: httpx.Request, timeout: Optional[float]) -> http.client.HTTPConnection:
+        url = request.url
+        key = (url.host, url.port)
+        conn: Optional[http.client.HTTPConnection] = getattr(self._local, "conn", None)
+        if conn is not None and getattr(self._local, "key", None) != key:
+            conn.close()
+            with self._lock:
+                self._conns.remove(conn)
+            conn = None
+        elif conn is not None and _stale(conn):
+            # http.client reopens a closed connection object on the next request.
+            conn.close()
+        if conn is None:
+            conn = http.client.HTTPConnection(url.host, url.port or 80, timeout=timeout)
+            self._local.conn, self._local.key = conn, key
+            with self._lock:
+                self._conns.append(conn)
+        elif conn.sock is not None:
+            conn.sock.settimeout(timeout)
+        conn.timeout = timeout
+        return conn
+
+    def handle_request(self, request: httpx.Request) -> httpx.Response:
+        timeout = _timeout(request)
+        conn = self._connection(request, timeout)
+        connecting = conn.sock is None
+        try:
+            conn.putrequest(request.method, request.url.raw_path.decode("ascii"), skip_host=True, skip_accept_encoding=True)
+            chunked = False
+            for name, value in request.headers.raw:
+                conn.putheader(name, value)
+                chunked = chunked or (name.lower() == b"transfer-encoding" and value.lower() == b"chunked")
+            body = request.read()
+            if chunked:
+                conn.endheaders([body] if body else [], encode_chunked=True)
+            else:
+                conn.endheaders(body or None)
+            res = conn.getresponse()
+            body = res.read()
+        except socket.timeout as exc:
+            conn.close()
+            raise (httpx.ConnectTimeout if connecting else httpx.ReadTimeout)(str(exc), request=request) from exc
+        except (http.client.HTTPException, ConnectionError) as exc:
+            conn.close()
+            if connecting and isinstance(exc, ConnectionRefusedError):
+                raise httpx.ConnectError(str(exc), request=request) from exc
+            raise httpx.RemoteProtocolError(str(exc) or type(exc).__name__, request=request) from exc
+        except OSError as exc:
+            conn.close()
+            raise (httpx.ConnectError if connecting else httpx.ReadError)(str(exc), request=request) from exc
+        if res.will_close:
+            conn.close()
+        return httpx.Response(
+            res.status,
+            headers=res.getheaders(),
+            stream=httpx.ByteStream(body),
+            request=request,
+            extensions={"http_version": b"HTTP/1.1", "reason_phrase": res.reason.encode("ascii", "replace")},
+        )
+
+    def close(self) -> None:
+        with self._lock:
+            conns, self._conns = self._conns, []
+        for conn in conns:
+            conn.close()