py-context-graph 0.1.0__tar.gz

py_context_graph-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,51 @@
+name: Bug Report
+description: Report something that isn't working correctly
+labels: ["bug"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: A clear description of the bug.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: Minimal code or steps to reproduce the issue.
+      placeholder: |
+        1. Install with `pip install py-context-graph[all]`
+        2. Run `python run.py`
+        3. ...
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: Output of `pip show py-context-graph | grep Version`
+      placeholder: "0.1.0"
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      description: Output of `python --version`
+      placeholder: "3.12.0"
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant logs or errors
+      description: Paste any error output here.
+      render: shell

py_context_graph-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,23 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or motivation
+      description: What problem does this solve, or why would it be useful?
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: How would you like it to work?
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Any other approaches you've thought about.

py_context_graph-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,13 @@
+## What does this PR do?
+
+<!-- Brief description of the change -->
+
+## Why?
+
+<!-- Link to issue or explain the motivation -->
+
+## Checklist
+
+- [ ] Tests pass (`PYTHONPATH=src:tests python -m unittest discover -s tests -p 'test_*.py'`)
+- [ ] New code has tests (if applicable)
+- [ ] CHANGELOG.md updated under `[Unreleased]` (if user-facing)

py_context_graph-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,54 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v6
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/py-context-graph/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v7
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/download-artifact@v7
+        with:
+          name: dist
+          path: dist/
+      - uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: dist/*

py_context_graph-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,24 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Run tests
+        run: PYTHONPATH=src:tests python -m unittest discover -s tests -p 'test_*.py'

py_context_graph-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+env/
+.env
+*.log
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+generated/
+.DS_Store

py_context_graph-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-04-02
+
+### Added
+- Decision extraction from unstructured conversation text via LLMs
+- Decision deduplication with configurable similarity scoring
+- LLM-based enrichment (topics, entities, constraints, key facts)
+- Cross-conversation decision clustering
+- Graph materialization with hydrated cluster output
+- Interactive HTML viewer with Insights dashboard, Cluster Board, Timeline, Person x Cluster matrix, and Explore (force-directed graph) views
+- Live pipeline progress in the viewer when running `python run.py`
+- In-memory backend (stores, TF-IDF vector index, graph store)
+- Google Cloud Firestore backend
+- LiteLLM adapter supporting OpenAI, Anthropic, and any LiteLLM provider
+- Context Graph query layer for natural language graph queries
+- Pluggable interfaces: `StorageBackend`, `LLMAdapter`, `VectorIndex`, `GraphStore`
+

py_context_graph-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing to py-context-graph
+
+Thanks for your interest in contributing! Here's how to get started.
+
+## Getting started
+
+```bash
+git clone https://github.com/ResearchifyLabs/py-context-graph.git
+cd py-context-graph
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Running tests
+
+```bash
+PYTHONPATH=src:tests python -m unittest discover -s tests -p 'test_*.py'
+```
+
+To run a specific test file:
+
+```bash
+PYTHONPATH=src:tests python -m unittest tests/test_example.py
+```
+
+## Project layout
+
+- `src/decision_graph/` — the library source
+- `tests/` — unit tests (stdlib `unittest`, not pytest)
+- `examples/` — runnable demos
+
+## How to contribute
+
+1. **Open an issue first** — describe the bug or feature so we can discuss before you write code.
+2. **Fork and branch** — create a feature branch from `main`.
+3. **Keep changes focused** — one PR per concern. Small PRs get reviewed faster.
+4. **Add tests** — if you're adding a feature or fixing a bug, add a test that covers it.
+5. **Make sure tests pass** — run the full test suite before opening a PR.
+
+## Code style
+
+- Keep it simple. No speculative abstractions.
+- Match the style of the surrounding code.
+- Avoid unnecessary comments — code should be self-documenting.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).

py_context_graph-0.1.0/LICENSE

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

py_context_graph-0.1.0/PKG-INFO

@@ -0,0 +1,271 @@
+Metadata-Version: 2.4
+Name: py-context-graph
+Version: 0.1.0
+Summary: Extract, enrich, cluster, and query decisions from unstructured conversations using LLMs.
+Project-URL: Homepage, https://github.com/ResearchifyLabs/py-context-graph
+Project-URL: Repository, https://github.com/ResearchifyLabs/py-context-graph
+Project-URL: Issues, https://github.com/ResearchifyLabs/py-context-graph/issues
+Project-URL: Changelog, https://github.com/ResearchifyLabs/py-context-graph/blob/main/CHANGELOG.md
+Author-email: ResearchifyLabs <care@researchify.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: clustering,context,conversations,decisions,knowledge-graph,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0
+Provides-Extra: all
+Requires-Dist: google-cloud-firestore; extra == 'all'
+Requires-Dist: litellm; extra == 'all'
+Requires-Dist: pandas; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: google-cloud-firestore; extra == 'dev'
+Requires-Dist: litellm; extra == 'dev'
+Requires-Dist: mock-firestore; extra == 'dev'
+Requires-Dist: pandas; extra == 'dev'
+Provides-Extra: firestore
+Requires-Dist: google-cloud-firestore; extra == 'firestore'
+Provides-Extra: llm
+Requires-Dist: litellm; extra == 'llm'
+Provides-Extra: memory
+Requires-Dist: pandas; extra == 'memory'
+Description-Content-Type: text/markdown
+
+# py-context-graph
+
+Extract, enrich, cluster, and query decisions from unstructured conversations using LLMs.
+
+[![Tests](https://github.com/ResearchifyLabs/py-context-graph/actions/workflows/test.yml/badge.svg)](https://github.com/ResearchifyLabs/py-context-graph/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/py-context-graph)](https://pypi.org/project/py-context-graph/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What is this?
+
+**py-context-graph** turns messy conversation text (meeting notes, Slack threads, standups) into a structured decision graph. It uses LLMs to:
+
+1. **Extract** decision items from text (what was decided, by whom, about what)
+2. **Deduplicate** near-identical decisions across conversations
+3. **Enrich** each decision with structured metadata (topics, entities, constraints, key facts)
+4. **Cluster** related decisions across conversations into coherent themes
+5. **Materialize** the result into a queryable graph
+
+```
+Text → Extract (LLM) → Persist → Deduplicate → Enrich (LLM) → Cluster → Graph
+```
+
+## Install
+
+```bash
+pip install py-context-graph
+```
+
+With optional backends:
+
+```bash
+pip install py-context-graph[all]       # LiteLLM + Firestore + in-memory vector index
+pip install py-context-graph[llm]       # LiteLLM adapter only
+pip install py-context-graph[firestore] # Google Cloud Firestore backend
+pip install py-context-graph[memory]    # In-memory TF-IDF vector index (pandas)
+```
+
+## Quick start
+
+```python
+import asyncio
+from decision_graph import DecisionGraph, LiteLLMAdapter
+from decision_graph.backends.memory import InMemoryBackend
+from decision_graph.backends.memory.stores import InMemoryGraphStore, InMemoryVectorIndex
+from decision_graph.decision_trace_pipeline import DecisionTracePipeline
+
+backend = InMemoryBackend()
+pipeline = DecisionTracePipeline(
+    backend=backend,
+    executor=LiteLLMAdapter(),
+    vector_index=InMemoryVectorIndex(),
+    graph_store=InMemoryGraphStore(),
+)
+
+async def main():
+    # Process a conversation
+    decisions = await pipeline.run_from_text(
+        conv_text="Alice: We decided to switch from REST to GraphQL for the new API...",
+        conv_id="standup-2024-01-15",
+        gid="engineering-team",
+        updated_at=1705334400.0,
+        summary_pid="summary_standup-2024-01-15",
+        query_gids=["engineering-team"],
+    )
+
+    # Query the results
+    dg = DecisionGraph(backend=backend, executor=LiteLLMAdapter())
+    service = dg.graph_service()
+    result = await service.get_enrichments_and_projections_joined(
+        group_ids=["engineering-team"]
+    )
+    print(f"Found {result['total_joined']} enriched decisions")
+
+asyncio.run(main())
+```
+
+## Key concepts
+
+### The four protocols
+
+py-context-graph is built around pluggable interfaces. You only implement what you need:
+
+| Protocol | Purpose | Bundled implementations |
+|----------|---------|------------------------|
+| **`StorageBackend`** | Groups 4 document stores (enrichments, projections, clusters, links) | `InMemoryBackend`, `FirestoreBackend` |
+| **`LLMAdapter`** | Executes LLM calls for extraction and enrichment | `LiteLLMAdapter` (supports OpenAI, Anthropic, and any LiteLLM provider) |
+| **`VectorIndex`** | Similarity search for cross-conversation clustering | `InMemoryVectorIndex` (TF-IDF + cosine) |
+| **`GraphStore`** | Write-only sync of hydrated clusters to a graph DB | `InMemoryGraphStore`, `NullGraphStore` |
+
+### DecisionGraph facade
+
+The main entry point. Wire a backend and LLM adapter, then access services:
+
+```python
+from decision_graph import DecisionGraph
+
+dg = DecisionGraph(backend=my_backend, executor=my_llm)
+service = dg.graph_service()        # query enrichments, projections, clusters
+retrieval = dg.retrieval()          # filtered queries over enrichments
+clusterer = dg.cluster_service()    # cluster management
+```
+
+### DecisionTracePipeline
+
+The end-to-end processing pipeline. Feed it text, get structured decisions:
+
+```python
+from decision_graph.decision_trace_pipeline import DecisionTracePipeline
+
+pipeline = DecisionTracePipeline(
+    backend=backend,
+    executor=llm_adapter,
+    vector_index=vector_index,    # optional, enables cross-conversation clustering
+    graph_store=graph_store,      # use NullGraphStore() to skip graph materialization
+)
+
+# From raw text
+decisions = await pipeline.run_from_text(conv_text=text, conv_id="c1", gid="g1", ...)
+
+# From pre-extracted decision items
+decisions = await pipeline.run(decision_items=[...], conv_id="c1", gid="g1", ...)
+```
+
+### Context Graph (query layer)
+
+For querying the materialized graph (requires a `GraphReader` implementation, e.g. Neo4j):
+
+```python
+from decision_graph.context_graph.service import ContextGraphService
+
+ctx = ContextGraphService(reader=my_graph_reader)
+result = await ctx.query(text="What decisions were made about the API?", mode="chat")
+```
+
+## Bring your own backend
+
+Implement `StorageBackend` to use any database:
+
+```python
+from decision_graph.core.registry import StorageBackend
+from decision_graph.core.interfaces import EnrichmentStore, ProjectionStore, ClusterStore, LinkStore
+
+class PostgresBackend(StorageBackend):
+    def enrichment_store(self) -> EnrichmentStore: ...
+    def projection_store(self) -> ProjectionStore: ...
+    def cluster_store(self) -> ClusterStore: ...
+    def link_store(self) -> LinkStore: ...
+```
+
+Each store protocol is defined in `decision_graph.core.interfaces` with clear method signatures.
+
+## Bring your own LLM
+
+Implement the `LLMAdapter` protocol:
+
+```python
+from decision_graph.core.interfaces import LLMAdapter
+
+class MyLLMAdapter(LLMAdapter):
+    async def execute_async(self, model_config, data, additional_data=None):
+        # Call your LLM, return parsed result
+        ...
+```
+
+## Examples
+
+See the [`examples/`](examples/) directory for a complete demo that:
+- Processes sample conversation files through the full pipeline
+- Shows live pipeline progress in the browser as conversations are processed
+- Generates an interactive HTML viewer with Insights dashboard, Cluster Board, Timeline, Person x Cluster matrix, and Explore (force-directed graph) views
+
+```bash
+cd examples
+pip install py-context-graph[all]
+export OPENAI_API_KEY=sk-...   # or any LiteLLM-supported provider
+python run.py                  # opens browser automatically
+```
+
+The viewer opens immediately and shows pipeline progress in real time. When processing completes, the dashboard appears with all visualizations.
+
+Options:
+- `python run.py --port 9000` — use a different port
+- `python run.py --no-browser` — don't auto-open the browser
+- `python run.py my_notes.txt` — process your own conversation files
+
+## Project structure
+
+```
+src/decision_graph/
+├── __init__.py                  # Public API: DecisionGraph, LLMAdapter, LLMConfig, LiteLLMAdapter
+├── graph.py                     # DecisionGraph facade
+├── decision_trace_pipeline.py   # End-to-end pipeline
+├── extraction_service.py        # LLM-based decision extraction
+├── enrichment_service.py        # LLM-based decision enrichment
+├── clustering_service.py        # Decision clustering
+├── retrieval.py                 # Query/filter over enrichments
+├── context_retrieval.py         # Vector-based context retrieval
+├── services.py                  # DecisionGraphService (joins, hydration)
+├── ingestion.py                 # Graph materialization helpers
+├── visualization.py             # vis.js graph builder
+├── markdown_chunker.py          # Split markdown by headings
+├── core/
+│   ├── interfaces.py            # Protocol definitions
+│   ├── registry.py              # StorageBackend ABC
+│   ├── domain.py                # Pydantic models
+│   ├── config.py                # LLMConfig
+│   └── matching.py              # Dedup, scoring, similarity
+├── llm/
+│   └── litellm_adapter.py       # LiteLLM-based LLMAdapter
+├── backends/
+│   ├── memory/                  # In-memory stores + TF-IDF vector index
+│   └── firestore/               # Google Cloud Firestore stores
+├── context_graph/               # Graph query layer (planner, templates, post-processing)
+└── prompts/                     # LLM prompt templates
+```
+
+## Contributing
+
+Contributions are welcome. Please open an issue first to discuss what you'd like to change.
+
+```bash
+git clone https://github.com/ResearchifyLabs/py-context-graph.git
+cd py-context-graph
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+PYTHONPATH=src:tests python -m unittest discover -s tests -p 'test_*.py'
+```
+
+## License
+
+[MIT](LICENSE)