intentmind 0.1.0__tar.gz

intentmind-0.1.0/LICENSE

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

intentmind-0.1.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: intentmind
+Version: 0.1.0
+Summary: Language-agnostic associative memory runtime for persistent AI systems
+Author: Intentmind Contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/avnialkan/intentmind
+Project-URL: Repository, https://github.com/avnialkan/intentmind
+Project-URL: Issues, https://github.com/avnialkan/intentmind/issues
+Keywords: ai,memory,agents,rag,graph,retrieval,embeddings
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Provides-Extra: faiss
+Requires-Dist: faiss-cpu>=1.7.0; extra == "faiss"
+Requires-Dist: numpy>=1.24; extra == "faiss"
+Provides-Extra: sentence-transformers
+Requires-Dist: sentence-transformers>=2.7.0; extra == "sentence-transformers"
+Provides-Extra: vis
+Requires-Dist: networkx>=3.0; extra == "vis"
+Requires-Dist: pyvis>=0.3.2; extra == "vis"
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
+Provides-Extra: llm
+Requires-Dist: openai>=1.0.0; extra == "llm"
+Requires-Dist: python-dotenv>=1.0.0; extra == "llm"
+Provides-Extra: api
+Requires-Dist: fastapi>=0.110.0; extra == "api"
+Requires-Dist: uvicorn[standard]>=0.29.0; extra == "api"
+Requires-Dist: openai>=1.0.0; extra == "api"
+Requires-Dist: python-dotenv>=1.0.0; extra == "api"
+Requires-Dist: sentence-transformers>=2.7.0; extra == "api"
+Requires-Dist: faiss-cpu>=1.7.0; extra == "api"
+Requires-Dist: numpy>=1.24; extra == "api"
+Provides-Extra: benchmark
+Requires-Dist: tqdm>=4.66.0; extra == "benchmark"
+Requires-Dist: openai>=1.0.0; extra == "benchmark"
+Requires-Dist: python-dotenv>=1.0.0; extra == "benchmark"
+Provides-Extra: all
+Requires-Dist: sentence-transformers>=2.7.0; extra == "all"
+Requires-Dist: networkx>=3.0; extra == "all"
+Requires-Dist: pyvis>=0.3.2; extra == "all"
+Requires-Dist: langchain-core>=0.1.0; extra == "all"
+Requires-Dist: faiss-cpu>=1.7.0; extra == "all"
+Requires-Dist: numpy>=1.24; extra == "all"
+Requires-Dist: openai>=1.0.0; extra == "all"
+Requires-Dist: python-dotenv>=1.0.0; extra == "all"
+Dynamic: license-file
+
+# Intentmind
+
+Intentmind is a lightweight associative memory runtime for AI assistants and
+agent systems. It stores memories as chunks, extracts intent nodes, connects
+co-occurring intents in a graph, and retrieves context through a mix of direct
+semantic match and graph traversal.
+
+The goal is to surface relevant context that a plain top-k vector search can
+miss when the user mentions a related concept instead of the exact old fact.
+
+## What It Is
+
+- A Python memory layer for LLM apps, assistants, copilots, and experiments.
+- A graph-backed recall runtime with explainable paths such as
+  `car -> insurance`.
+- A small library API: `add`, `query`, `save`, `load`, `tick`,
+  `graph_summary`, and `visualize`.
+- Optional integrations for FAISS, SentenceTransformers, LangChain, and a demo
+  FastAPI/React chat UI.
+
+Intentmind is not a full agent framework, vector database, hosted service, or
+chatbot by itself.
+
+## Quick Start
+
+```bash
+pip install -e ".[dev]"
+```
+
+```python
+from intentmind import IntentmindMemory
+
+mem = IntentmindMemory(is_test=True)
+
+mem.add("I need car insurance but I have no money.")
+mem.add("I bought a new car and will drive to London.")
+
+result = mem.query("I have a car and I am going to London.")
+
+for item in result["memories"]["items"]:
+    print(item["layer"], item["intent"], item["path"], item["text"])
+```
+
+For production embeddings:
+
+```bash
+pip install -e ".[sentence-transformers]"
+```
+
+```python
+from intentmind import IntentmindMemory
+from intentmind.embeddings import SentenceTransformerEmbedder
+
+mem = IntentmindMemory(embedder=SentenceTransformerEmbedder())
+```
+
+## Optional Features
+
+```bash
+pip install -e ".[faiss]"       # FAISS-backed intent index
+pip install -e ".[langchain]"   # LangChain retriever adapter
+pip install -e ".[vis]"         # graph visualization
+pip install -e ".[llm]"         # OpenAI-backed intent extraction examples
+pip install -e ".[api]"         # FastAPI demo backend dependencies
+```
+
+If you use OpenAI-backed examples or the demo API, create a local `.env` from
+`.env.example` and set `OPENAI_API_KEY`.
+
+## Core API
+
+```python
+chunk_id = mem.add("The car insurance expires next week.", source="user")
+result = mem.query("I am planning a road trip.")
+
+print(result["prompt"])
+print(result["memories"]["items"])
+print(result["trace"])
+print(result["cognitive_field"])
+```
+
+Each accepted memory item includes the chunk text, score, layer, triggering
+intent, path, reason, and edge metadata when the item was reached through the
+graph.
+
+## How Recall Works
+
+1. `add()` embeds the memory chunk and extracts candidate intents.
+2. Intents are reused or created, then co-occurrence edges are reinforced.
+3. `query()` extracts query intents, activates matching graph nodes, and runs a
+   query-time cognitive field step.
+4. Recall selects direct memories, one-hop associated memories, and optional
+   weak echo memories.
+5. `PromptBuilder` assembles an LLM-ready prompt with relevant memories and
+   traceable context.
+
+## Persistence
+
+```python
+mem.save("memory_snapshot.json")
+restored = IntentmindMemory.load("memory_snapshot.json", is_test=True)
+```
+
+Generated memory snapshots are ignored by default so local experiments do not
+leak into the repository.
+
+## LangChain Adapter
+
+```python
+from intentmind import IntentmindMemory
+from intentmind.integrations.langchain import IntentmindRetriever
+
+memory = IntentmindMemory(is_test=True)
+retriever = IntentmindRetriever(memory=memory)
+docs = retriever.invoke("How does the energy model work?")
+```
+
+## Demo API And UI
+
+Backend:
+
+```bash
+pip install -e ".[api]"
+$env:PYTHONPATH="src"; python api.py
+```
+
+UI:
+
+```bash
+cd ui
+npm install
+npm run dev
+```
+
+The UI expects `POST /api/chat` to be reachable from the same origin or through
+a local proxy.
+
+## Benchmarks
+
+Benchmark fixtures live under `tests/fixtures`. They are useful for regression
+testing and local comparison against a classic vector-search baseline, but they
+should not be treated as independent research claims.
+
+```bash
+$env:PYTHONPATH="src"; python examples/run_benchmark.py
+$env:PYTHONPATH="src"; python examples/run_real_world_benchmark.py
+```
+
+Generated benchmark outputs are ignored by Git.
+
+## Development
+
+```bash
+$env:PYTHONPATH="src"; python -m pytest -q
+cd ui
+npm install
+npm run lint
+npm run build
+```
+
+Current local verification: `26 passed`; UI lint and production build pass.
+
+## Repository Layout
+
+```text
+src/intentmind/          Python package
+tests/                   Unit and regression tests
+tests/fixtures/          Deterministic benchmark fixtures
+examples/                Usage demos and benchmark runners
+ui/                      Optional React/Vite demo
+api.py                   Optional FastAPI demo backend
+```
+
+## License
+
+MIT. See `LICENSE`.

intentmind-0.1.0/README.md

@@ -0,0 +1,176 @@
+# Intentmind
+
+Intentmind is a lightweight associative memory runtime for AI assistants and
+agent systems. It stores memories as chunks, extracts intent nodes, connects
+co-occurring intents in a graph, and retrieves context through a mix of direct
+semantic match and graph traversal.
+
+The goal is to surface relevant context that a plain top-k vector search can
+miss when the user mentions a related concept instead of the exact old fact.
+
+## What It Is
+
+- A Python memory layer for LLM apps, assistants, copilots, and experiments.
+- A graph-backed recall runtime with explainable paths such as
+  `car -> insurance`.
+- A small library API: `add`, `query`, `save`, `load`, `tick`,
+  `graph_summary`, and `visualize`.
+- Optional integrations for FAISS, SentenceTransformers, LangChain, and a demo
+  FastAPI/React chat UI.
+
+Intentmind is not a full agent framework, vector database, hosted service, or
+chatbot by itself.
+
+## Quick Start
+
+```bash
+pip install -e ".[dev]"
+```
+
+```python
+from intentmind import IntentmindMemory
+
+mem = IntentmindMemory(is_test=True)
+
+mem.add("I need car insurance but I have no money.")
+mem.add("I bought a new car and will drive to London.")
+
+result = mem.query("I have a car and I am going to London.")
+
+for item in result["memories"]["items"]:
+    print(item["layer"], item["intent"], item["path"], item["text"])
+```
+
+For production embeddings:
+
+```bash
+pip install -e ".[sentence-transformers]"
+```
+
+```python
+from intentmind import IntentmindMemory
+from intentmind.embeddings import SentenceTransformerEmbedder
+
+mem = IntentmindMemory(embedder=SentenceTransformerEmbedder())
+```
+
+## Optional Features
+
+```bash
+pip install -e ".[faiss]"       # FAISS-backed intent index
+pip install -e ".[langchain]"   # LangChain retriever adapter
+pip install -e ".[vis]"         # graph visualization
+pip install -e ".[llm]"         # OpenAI-backed intent extraction examples
+pip install -e ".[api]"         # FastAPI demo backend dependencies
+```
+
+If you use OpenAI-backed examples or the demo API, create a local `.env` from
+`.env.example` and set `OPENAI_API_KEY`.
+
+## Core API
+
+```python
+chunk_id = mem.add("The car insurance expires next week.", source="user")
+result = mem.query("I am planning a road trip.")
+
+print(result["prompt"])
+print(result["memories"]["items"])
+print(result["trace"])
+print(result["cognitive_field"])
+```
+
+Each accepted memory item includes the chunk text, score, layer, triggering
+intent, path, reason, and edge metadata when the item was reached through the
+graph.
+
+## How Recall Works
+
+1. `add()` embeds the memory chunk and extracts candidate intents.
+2. Intents are reused or created, then co-occurrence edges are reinforced.
+3. `query()` extracts query intents, activates matching graph nodes, and runs a
+   query-time cognitive field step.
+4. Recall selects direct memories, one-hop associated memories, and optional
+   weak echo memories.
+5. `PromptBuilder` assembles an LLM-ready prompt with relevant memories and
+   traceable context.
+
+## Persistence
+
+```python
+mem.save("memory_snapshot.json")
+restored = IntentmindMemory.load("memory_snapshot.json", is_test=True)
+```
+
+Generated memory snapshots are ignored by default so local experiments do not
+leak into the repository.
+
+## LangChain Adapter
+
+```python
+from intentmind import IntentmindMemory
+from intentmind.integrations.langchain import IntentmindRetriever
+
+memory = IntentmindMemory(is_test=True)
+retriever = IntentmindRetriever(memory=memory)
+docs = retriever.invoke("How does the energy model work?")
+```
+
+## Demo API And UI
+
+Backend:
+
+```bash
+pip install -e ".[api]"
+$env:PYTHONPATH="src"; python api.py
+```
+
+UI:
+
+```bash
+cd ui
+npm install
+npm run dev
+```
+
+The UI expects `POST /api/chat` to be reachable from the same origin or through
+a local proxy.
+
+## Benchmarks
+
+Benchmark fixtures live under `tests/fixtures`. They are useful for regression
+testing and local comparison against a classic vector-search baseline, but they
+should not be treated as independent research claims.
+
+```bash
+$env:PYTHONPATH="src"; python examples/run_benchmark.py
+$env:PYTHONPATH="src"; python examples/run_real_world_benchmark.py
+```
+
+Generated benchmark outputs are ignored by Git.
+
+## Development
+
+```bash
+$env:PYTHONPATH="src"; python -m pytest -q
+cd ui
+npm install
+npm run lint
+npm run build
+```
+
+Current local verification: `26 passed`; UI lint and production build pass.
+
+## Repository Layout
+
+```text
+src/intentmind/          Python package
+tests/                   Unit and regression tests
+tests/fixtures/          Deterministic benchmark fixtures
+examples/                Usage demos and benchmark runners
+ui/                      Optional React/Vite demo
+api.py                   Optional FastAPI demo backend
+```
+
+## License
+
+MIT. See `LICENSE`.

intentmind-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "intentmind"
+version = "0.1.0"
+description = "Language-agnostic associative memory runtime for persistent AI systems"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "Intentmind Contributors" }
+]
+keywords = ["ai", "memory", "agents", "rag", "graph", "retrieval", "embeddings"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://github.com/avnialkan/intentmind"
+Repository = "https://github.com/avnialkan/intentmind"
+Issues = "https://github.com/avnialkan/intentmind/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+]
+faiss = [
+    "faiss-cpu>=1.7.0",
+    "numpy>=1.24",
+]
+sentence-transformers = ["sentence-transformers>=2.7.0"]
+vis = ["networkx>=3.0", "pyvis>=0.3.2"]
+langchain = ["langchain-core>=0.1.0"]
+llm = ["openai>=1.0.0", "python-dotenv>=1.0.0"]
+api = [
+    "fastapi>=0.110.0",
+    "uvicorn[standard]>=0.29.0",
+    "openai>=1.0.0",
+    "python-dotenv>=1.0.0",
+    "sentence-transformers>=2.7.0",
+    "faiss-cpu>=1.7.0",
+    "numpy>=1.24",
+]
+benchmark = ["tqdm>=4.66.0", "openai>=1.0.0", "python-dotenv>=1.0.0"]
+all = [
+    "sentence-transformers>=2.7.0",
+    "networkx>=3.0",
+    "pyvis>=0.3.2",
+    "langchain-core>=0.1.0",
+    "faiss-cpu>=1.7.0",
+    "numpy>=1.24",
+    "openai>=1.0.0",
+    "python-dotenv>=1.0.0",
+]

intentmind-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

intentmind-0.1.0/src/intentmind/__init__.py

@@ -0,0 +1,3 @@
+from .runtime import IntentmindMemory
+
+__all__ = ["IntentmindMemory"]

intentmind-0.1.0/src/intentmind/benchmark/__init__.py

@@ -0,0 +1,3 @@
+from .runner import BenchmarkRunner
+
+__all__ = ["BenchmarkRunner"]