tinysuite-context 0.1.0__tar.gz

tinysuite_context-0.1.0/LICENSE

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

tinysuite_context-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include tests *.py

tinysuite_context-0.1.0/NOTICE

@@ -0,0 +1,19 @@
+TinyContext
+Copyright (c) 2026 MarcellM01
+
+TinyContext source code is licensed under the MIT License. See LICENSE.
+
+The Docker image installs third-party Python packages from requirements.txt and
+their transitive dependencies. Those packages remain under their respective
+upstream licenses.
+
+TinyContext does not commit or bake ONNX embedding model files into this
+repository or Docker image. When the ONNX backend is enabled, the running
+application may download the selected model bundle from Hugging Face into the
+configured models directory. Those model files are separate distributions under
+their upstream model-card licenses.
+
+The default fast embedding bundle is derived from all-MiniLM-L6-v2 and is
+Apache-2.0. The balanced and quality presets use BAAI bge model bundles; check
+their Hugging Face model cards before redistributing images, volumes, or
+archives that include downloaded weights.

tinysuite_context-0.1.0/PKG-INFO

@@ -0,0 +1,356 @@
+Metadata-Version: 2.4
+Name: tinysuite-context
+Version: 0.1.0
+Summary: Token-light local memory with SQLite hybrid retrieval for AI agents.
+Author: MarcellM01
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/TinySuiteHQ/TinyContext
+Project-URL: Repository, https://github.com/TinySuiteHQ/TinyContext
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: tiktoken==0.12.0
+Requires-Dist: rank-bm25==0.2.2
+Requires-Dist: platformdirs<5,>=4
+Requires-Dist: huggingface_hub==0.36.0
+Requires-Dist: onnxruntime<2,>=1.17.0
+Requires-Dist: tokenizers<1,>=0.15.0
+Requires-Dist: numpy<3,>=1.26
+Requires-Dist: sqlite-vec==0.1.9
+Provides-Extra: server
+Requires-Dist: fastapi==0.136.1; extra == "server"
+Requires-Dist: uvicorn==0.46.0; extra == "server"
+Requires-Dist: mcp==1.28.1; extra == "server"
+Dynamic: license-file
+
+# TinyContext
+
+<!-- mcp-name: io.github.TinySuiteHQ/tinycontext -->
+
+**Context that fits your local LLMs.**
+
+[![PyPI version](https://img.shields.io/pypi/v/tinysuite-context?label=pypi)](https://pypi.org/project/tinysuite-context/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Release](https://img.shields.io/github/v/release/TinySuiteHQ/TinyContext?label=release)](https://github.com/TinySuiteHQ/TinyContext/releases)
+[![Docker Pulls](https://img.shields.io/docker/pulls/marcellm01/tinycontext?label=docker%20pulls)](https://hub.docker.com/r/marcellm01/tinycontext)
+![MCP Server](https://img.shields.io/badge/MCP-server-blue)
+![FastAPI](https://img.shields.io/badge/FastAPI-supported-009688)
+
+TinyContext is a token-light local memory layer for AI agents. It stores concise
+memories and their embeddings in SQLite, ranks them with hybrid BM25 and dense
+retrieval, and returns only the context that fits the requested token budget.
+
+No hosted account. No giant context dumps. No required vector database.
+
+## Choose a tier
+
+| Tier | Use it when | Entry point |
+| --- | --- | --- |
+| Python library | You are building an agent or Python application | `pip install tinysuite-context` |
+| One-command MCP | An MCP client should launch TinyContext for you | `uvx --python 3.12 --from "tinysuite-context[server]" tinycontext` |
+| Docker | You want persistent self-hosted storage and HTTP MCP | `docker compose ... up -d` |
+
+The Python library contains the memory engine. MCP, FastAPI, and Docker are
+adapters around the same `save_memories` and `recall_memories` operations.
+
+## One-command MCP
+
+Add TinyContext to any stdio MCP client:
+
+```json
+{
+  "mcpServers": {
+    "tinycontext": {
+      "command": "uvx",
+      "args": [
+        "--python",
+        "3.12",
+        "--from",
+        "tinysuite-context[server]",
+        "tinycontext"
+      ]
+    }
+  }
+}
+```
+
+The no-argument `tinycontext` command runs stdio MCP. On its first launch,
+TinyContext downloads the selected ONNX embedding bundle into its per-user data
+directory. The database is created lazily on the first save or recall. Later
+launches reuse both local assets.
+
+Check the resolved configuration and storage readiness with:
+
+```bash
+uvx --python 3.12 --from "tinysuite-context[server]" tinycontext doctor
+```
+
+TinyContext exposes two tools:
+
+```text
+save_memories(memories)
+recall_memories(query)
+```
+
+- Use `save_memories` for durable facts, preferences, decisions, and research notes.
+- Use `recall_memories` before answering when previous context may help.
+
+## Python library
+
+Install only the transport-independent core:
+
+```bash
+pip install tinysuite-context
+```
+
+```python
+from pathlib import Path
+
+from tinycontext import (
+    MemoryInput,
+    TinyContextConfig,
+    recall_memories,
+    save_memories,
+)
+
+config = TinyContextConfig(
+    memory_db_path=str(Path("agent-memory.db").resolve()),
+    recall_max_tokens=800,
+)
+
+save_memories(
+    [
+        MemoryInput(
+            content="The project uses SQLite for local state.",
+            tags=["architecture"],
+            metadata={"source": "design-session"},
+        )
+    ],
+    session_id="project-a",
+    config=config,
+)
+
+result = recall_memories(
+    "How does the project store state?",
+    session_id="project-a",
+    config=config,
+)
+
+for memory in result["memories"]:
+    print(memory["content"])
+```
+
+Programmatic configuration does not read environment variables or depend on the
+checkout. Passing no config uses the per-user data directory returned by
+`platformdirs`.
+
+## Docker
+
+Run the published image as an MCP server over Streamable HTTP:
+
+```bash
+docker compose -f "https://github.com/TinySuiteHQ/TinyContext.git#main:compose.quickstart.yaml" up -d
+```
+
+Connect an MCP client to:
+
+```json
+{
+  "mcpServers": {
+    "tinycontext": {
+      "url": "http://localhost:8000/mcp"
+    }
+  }
+}
+```
+
+The `data` volume persists `/data/memories.db` and `/data/models`.
+
+Stop the service with:
+
+```bash
+docker compose -f "https://github.com/TinySuiteHQ/TinyContext.git#main:compose.quickstart.yaml" down
+```
+
+For a local image build:
+
+```bash
+docker compose up -d --build
+```
+
+The optional FastAPI profile uses the same image:
+
+```bash
+docker compose --profile fastapi up -d --build
+```
+
+- MCP Streamable HTTP: `http://localhost:8000/mcp`
+- FastAPI: `http://localhost:8001`
+
+## How recall works
+
+```mermaid
+flowchart LR
+    A[Agent] --> B[save_memories]
+    A --> C[recall_memories]
+    B --> D[(SQLite)]
+    C --> D
+    C --> E[BM25 rank]
+    C --> G[sqlite-vec cosine rank]
+    E --> H[Weighted RRF]
+    G --> H
+    H --> F[Token budget trim]
+    F --> A
+```
+
+1. Generate embeddings locally with the selected ONNX model.
+2. Save text, metadata, and float32 embedding BLOBs in the same SQLite row.
+3. Filter by `session_id`, rank lexical matches with BM25, and calculate cosine
+   similarity in SQLite through `sqlite-vec`.
+4. Fuse both rankings with weighted reciprocal rank fusion (RRF).
+5. Return the highest-ranked memories within the token budget.
+
+Existing TinyContext databases are upgraded in place with nullable embedding
+columns. The first recall backfills embeddings for legacy rows; no database
+migration command or separate vector service is required.
+
+## FastAPI
+
+The optional HTTP API mirrors the two MCP tools.
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| GET | `/health` | Liveness |
+| POST/GET | `/save_memories` | Persist one or more memories |
+| POST/GET | `/recall_memories` | Recall ranked memories within a token budget |
+
+Install and run it directly:
+
+```bash
+pip install "tinysuite-context[server]"
+uvicorn tinycontext.servers.fastapi_server:app --host 0.0.0.0 --port 8000
+```
+
+### Save request
+
+```json
+{
+  "session_id": "optional-session",
+  "memories": [
+    {
+      "content": "User prefers concise answers",
+      "tags": ["preference"],
+      "metadata": {"source": "chat"}
+    }
+  ]
+}
+```
+
+### Recall request
+
+```json
+{
+  "query": "user preferences",
+  "session_id": "optional-session",
+  "max_tokens": 2000,
+  "top_k": 10
+}
+```
+
+### Error codes
+
+| Code | HTTP | Meaning |
+| --- | --- | --- |
+| `empty_memory` | 400 | Missing or blank memory content/query |
+| `session_not_found` | 404 | No memories exist for the requested session |
+| `recall_budget` | 400 | Invalid recall budget parameters |
+| `internal_error` | 500 | Unexpected server error |
+
+## Configuration
+
+The core defaults are:
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `memory_db_path` | Per-user TinyContext data directory | SQLite database |
+| `recall_top_k` | `10` | Maximum memories considered |
+| `recall_max_tokens` | `2000` | Default recall token budget |
+| `encoding_name` | `o200k_base` | Tokenizer used for budgeting |
+| `models_dir` | Per-user TinyContext data directory | Downloaded ONNX bundles |
+| `embedding_model` | `fast` | `fast`, `balanced`, `quality`, or a Hugging Face repository |
+| `embedding_batch_size` | `32` | Local ONNX inference batch size |
+| `recall_dense_weight` | `0.5` | Dense contribution to weighted RRF |
+| `recall_rrf_k` | `60` | RRF rank constant |
+| `dense_query_prefix` | empty | Optional text prepended before embedding queries |
+| `dense_document_prefix` | empty | Optional text prepended before embedding memories |
+
+Server processes look for `context_config.json` in the per-user TinyContext
+configuration directory. A relative `memory_db_path` inside a JSON config is
+resolved relative to that file.
+
+Environment overrides:
+
+| Variable | Purpose |
+| --- | --- |
+| `TINYCONTEXT_CONFIG_PATH` | Use an explicit JSON configuration file |
+| `TINYCONTEXT_MEMORY_DB_PATH` | Override the SQLite database path |
+| `TINYCONTEXT_RECALL_TOP_K` | Override the default candidate count |
+| `TINYCONTEXT_RECALL_MAX_TOKENS` | Override the default token budget |
+| `TINYCONTEXT_ENCODING_NAME` | Override the tokenizer |
+| `TINYCONTEXT_MODELS_DIR` | Override the ONNX bundle directory |
+| `TINYCONTEXT_EMBEDDING_MODEL` | Override the embedding model |
+| `TINYCONTEXT_EMBEDDING_BATCH_SIZE` | Override inference batch size |
+| `TINYCONTEXT_RECALL_DENSE_WEIGHT` | Override the dense RRF weight |
+| `TINYCONTEXT_RECALL_RRF_K` | Override the RRF rank constant |
+| `TINYCONTEXT_DENSE_QUERY_PREFIX` | Override the dense query prefix |
+| `TINYCONTEXT_DENSE_DOCUMENT_PREFIX` | Override the dense document prefix |
+| `TINYCONTEXT_VERSION` | Set the FastAPI/container version |
+| `MCP_TRANSPORT` | `stdio`, `sse`, or `streamable-http` |
+| `MCP_HOST` | MCP HTTP bind host |
+| `MCP_PORT` | MCP HTTP bind port |
+| `MCP_CORS_ORIGINS` | Comma-separated CORS origins |
+
+An existing checkout-local database remains usable:
+
+```bash
+TINYCONTEXT_MEMORY_DB_PATH=/absolute/path/to/TinyContext/data/memories.db tinycontext
+```
+
+## Development
+
+```bash
+git clone https://github.com/TinySuiteHQ/TinyContext
+cd TinyContext
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[server]"
+python -m unittest discover tests
+python scripts/smoke_mcp_stdio.py
+```
+
+TinyContext supports Python 3.12 and newer. CI tests Python 3.12, 3.13, and
+3.14 across Linux, macOS, and Windows.
+
+Source-checkout compatibility shims remain available:
+
+```bash
+python servers/mcp_server.py
+uvicorn servers.fastapi_server:app --host 0.0.0.0 --port 8000
+```
+
+## Entrypoints
+
+- `tinycontext.save_memories` and `tinycontext.recall_memories`: Python API
+- `tinycontext` / `tinycontext mcp`: stdio MCP
+- `tinycontext serve`: Streamable HTTP MCP
+- `tinycontext doctor`: configuration and storage readiness
+- `tinycontext.servers.fastapi_server:app`: optional FastAPI application
+
+## License
+
+MIT. See [LICENSE](LICENSE) and [NOTICE](NOTICE).