trellis-ai 0.3.2__tar.gz

trellis_ai-0.3.2/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Virtual environments
+.venv/
+venv/
+
+# Tools
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+# Data
+data/
+*.db
+
+# Environment
+.env
+pytest-of-*
+tmp*

trellis_ai-0.3.2/CHANGELOG.md

@@ -0,0 +1,109 @@
+# Changelog
+
+All notable changes to Trellis will be documented in this file.
+
+## [Unreleased]
+
+## [0.3.2] - 2026-04-17
+
+### Fixed
+
+- Publish workflow's `publish` job failed at `actions/checkout` with "repository not found" because the explicit `permissions: id-token: write` block implicitly set `contents: none`. Added `contents: read` alongside the OIDC token permission.
+
+## [0.3.1] - 2026-04-17
+
+### Fixed
+
+- `mypy` error in [`src/trellis_sdk/async_client.py`](src/trellis_sdk/async_client.py) that blocked the `test` job in the publish workflow. The `type: ignore[arg-type]` was on the wrong line inside a multi-line `httpx.AsyncClient(...)` call. The initial `v0.3.0` tag never produced a PyPI artifact — this is the first actual release.
+
+## [0.3.0] - 2026-04-17
+
+### Breaking changes
+
+- **Removed `trellis-mcp-legacy` entry point** and deleted `src/trellis/mcp_server.py`. The current MCP server lives at `src/trellis/mcp/server.py` and is exposed as `trellis-mcp`. Anyone invoking `trellis-mcp-legacy` should switch to `trellis-mcp`.
+- **Removed `[langgraph]` optional extra.** The LangGraph integration is no longer shipped in the wheel — it lives in [`examples/integrations/langgraph/`](examples/integrations/langgraph/) as a copy-paste reference template. Install `langgraph` and `langchain-core` directly in your project and copy `tools.py` in.
+- **Moved `integrations/` to `examples/integrations/`.** None of the integrations (LangGraph, Obsidian, OpenClaw) ship in the wheel. They are reference templates you copy into your project. Test imports updated from `integrations.obsidian.*` to `examples.integrations.obsidian.*`.
+
+### Added
+
+- **PyPI publishing pipeline**: trusted-publisher (OIDC) workflow, `make build`/`verify-wheel`/`publish-check` targets, `workflow_dispatch` re-run path, `twine check` step, [RELEASING.md](RELEASING.md) runbook.
+- **Examples directory** ([`examples/`](examples/)): SDK local + remote demos, retrieve→act→record loop, custom extractor, custom classifier, LangGraph agent, batch ingest script, and an MCP-from-Claude-Code walkthrough.
+- **Skill templates** ([`skills/`](skills/)): drop-in Claude Code skills for `retrieve-before-task`, `record-after-task`, `link-evidence`.
+- **MCP setup guides** for Claude Code, Cursor, and Claude Desktop in [`docs/getting-started/`](docs/getting-started/).
+- **GitHub repo hygiene**: issue templates (bug, feature, config), PR template.
+- **Python 3.13 support** added to CI matrix and PyPI classifiers.
+- **`py.typed` markers** for `trellis_cli`, `trellis_sdk`, `trellis_api`, `trellis_workers` so type checkers see them as typed (`trellis` already had one).
+
+### Changed
+
+- **MCP server documentation now lists 11 tools, not 8.** The three sectioned-context tools (`get_objective_context`, `get_task_context`, `get_sectioned_context`) were already in the server but missing from every doc surface. Updated [docs/agent-guide/operations.md](docs/agent-guide/operations.md), [examples/integrations/openclaw/SKILL.md](examples/integrations/openclaw/SKILL.md), [README.md](README.md), and the IDE setup guides.
+- **README links rewritten to absolute URLs** so they render correctly on PyPI.
+
+## [0.2.0] - 2026-04-01
+
+### Added
+
+- **Classification Layer**: Hybrid deterministic + LLM tagging pipeline for all ingested content
+  - Four orthogonal tag facets: `domain`, `content_type`, `scope`, `signal_quality`
+  - Four deterministic classifiers: `StructuralClassifier`, `KeywordDomainClassifier`, `SourceSystemClassifier`, `GraphNeighborClassifier`
+  - `LLMFacetClassifier` for async enrichment of ambiguous items (fires only when confidence < threshold)
+  - `ClassifierPipeline` with two modes: ingestion (deterministic-only, microseconds) and enrichment (+ LLM fallback)
+  - `compute_importance()` combining tags with LLM base scores for relevance ranking
+  - `apply_noise_tags()` feedback loop: effectiveness analysis flags low-value items as noise, excluding them from future packs
+  - Tag-based pre-filtering in `PackBuilder` (noise items excluded by default)
+
+- **Web UI Foundation**: Dashboard served at `/ui` when running `trellis admin serve`
+  - Live store stats (traces, documents, nodes, edges, events)
+  - Store health status
+  - Placeholder views for Graph Explorer, Evolution, Traces, and Precedents
+  - Static files bundled in the PyPI wheel — no separate install needed
+
+- **UI Design Documents**: Comprehensive design for full interactive UI
+  - Graph Explorer with force-directed layout and time-travel slider
+  - Evolution View: learning curve chart, pack composition drift, item lifecycle, domain generations
+  - Trace Timeline, Improvement Dashboard, Precedent Library
+  - ASCII wireframes, data flow diagrams, backend schema proposals
+  - Demo scenario specification (8-week improvement arc from 40% to 85% success rate)
+
+- **Package extras**: `all` convenience extra (`pip install trellis-ai[all]`)
+
+### Changed
+
+- FastAPI app version bumped to 0.2.0
+- Fallback version updated to 0.2.0
+
+### Fixed
+
+- 22 code review issues across correctness, efficiency, and quality
+  - `json_each` JOIN for multi-label domain filtering in SQLite stores
+  - `get_node_history` ordering (DESC by `valid_from` for newest-first)
+  - `StoreRegistry.close()` safety for partially initialized registries
+  - `_emit_telemetry` exception handling in PackBuilder
+  - Bounded idempotency cache (10K max) in MutationExecutor
+  - `Content-Type` validation in API ingest routes
+  - Defensive keyword extraction in `KeywordDomainClassifier`
+  - `classification_version` default set to `"1"` in ContentTags
+
+## [0.1.0] - 2025-12-15
+
+### Added
+
+- Initial release
+- Core library (`trellis`): schemas, stores, mutation executor, retrieval, MCP server
+- CLI (`trellis`): admin, ingest, retrieve, curate, analyze commands
+- REST API (`trellis-api`): FastAPI server on port 8420
+- Python SDK (`trellis_sdk`): dual-mode client (local or remote via httpx)
+- Background workers (`trellis_workers`): ingestion (dbt, OpenLineage), maintenance
+- Six store ABCs: TraceStore, DocumentStore, GraphStore, VectorStore, EventLog, BlobStore
+- SQLite default backends with PostgreSQL cloud backends
+- SCD Type 2 temporal versioning on graph nodes (time-travel via `as_of`)
+- 13 edge types for entity relationships
+- Governed mutation pipeline: validate, policy check, idempotency, execute, emit
+- Context pack builder with keyword, semantic, graph, and recency search strategies
+- Token-budgeted retrieval with two-stage limits (max_items, max_tokens)
+- MCP server with 8 macro tools for Claude and other MCP clients
+- OpenClaw skill for Claude Code integration
+- LangGraph integration
+- Obsidian vault indexer
+- Effectiveness analysis and feedback loop
+- Token usage tracking and telemetry

trellis_ai-0.3.2/CODE_OF_CONDUCT.md

@@ -0,0 +1,52 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainers at the email address listed in SECURITY.md.
+All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/),
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).

trellis_ai-0.3.2/CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# Contributing to Trellis
+
+Thanks for your interest in contributing! This guide covers the essentials.
+
+## Development Setup
+
+```bash
+# Clone and install with dev dependencies
+git clone https://github.com/ronsse/trellis-ai.git
+cd trellis-ai
+uv pip install -e ".[dev]"
+
+# Initialize stores (needed for integration-style tests)
+trellis admin init
+```
+
+## Quality Checks
+
+Run all checks before submitting a PR:
+
+```bash
+make format      # Auto-format with ruff
+make lint        # Lint check
+make typecheck   # mypy strict type checking
+make test        # Full test suite
+```
+
+Or run them individually:
+
+```bash
+ruff format src/ tests/          # Format
+ruff check src/ tests/           # Lint
+mypy src/                        # Type check
+pytest tests/ -v                 # Tests
+pytest tests/unit/stores/ -v     # Single directory
+```
+
+## Project Structure
+
+```
+src/
+  trellis/          # Core library (schemas, stores, mutations, retrieval, MCP)
+  trellis_cli/      # CLI (trellis command)
+  trellis_api/      # REST API (FastAPI)
+  trellis_sdk/      # Client SDK (local or remote)
+  trellis_workers/  # Background workers (classification, ingestion)
+tests/
+  unit/             # Mirrors src/ layout
+docs/
+  agent-guide/      # Operational reference for AI agents
+```
+
+## How to Add a Store Backend
+
+1. Create `src/trellis/stores/<backend>/` with implementations for the ABCs in `stores/base/` (TraceStore, DocumentStore, GraphStore, VectorStore, EventLog, BlobStore).
+2. Register the backend in `stores/registry.py` so `StoreRegistry.from_config_dir()` can instantiate it from config.
+3. Add tests in `tests/unit/stores/` using `tmp_path` fixtures.
+
+## How to Add a Search Strategy
+
+1. Subclass `SearchStrategy` in `src/trellis/retrieve/strategies.py` (or a new module under `retrieve/`).
+2. Implement `name` property and `search()` method returning `list[PackItem]`.
+3. Wire it into `build_strategies()` or document how users can add it to `PackBuilder`.
+
+## How to Extend Classification
+
+1. Implement the `Classifier` protocol in `src/trellis/classify/`.
+2. Register it in `ClassifierPipeline` — deterministic classifiers run inline at ingest time.
+3. Add tests with synthetic items covering each classification decision.
+
+## Pull Request Process
+
+1. Branch from `main`. Use descriptive branch names (`feat/reranker-protocol`, `fix/session-dedup`).
+2. All PRs run lint, typecheck, and test workflows automatically.
+3. Keep PRs focused — one feature or fix per PR.
+4. Write tests for new functionality. Target the existing test style: unit-scoped, `tmp_path` for stores, `MagicMock(spec=...)` for protocols.
+5. Update `docs/agent-guide/` if your change affects the agent-facing API.
+
+## AI-Assisted Development
+
+This project uses Claude Code for development. The `CLAUDE.md` file at the repo root provides context and rules for AI-assisted work. PRs authored or co-authored by AI are welcome — just include the `Co-Authored-By` trailer.
+
+## Code Style
+
+- **Type hints** on all public APIs.
+- **`structlog`** for logging (never `print()` in library code).
+- **`extra="forbid"`** on all Pydantic models (via `TrellisModel` base).
+- **Ruff** for formatting and linting — the pre-commit hook enforces this.
+
+## Questions?
+
+Open a [GitHub Discussion](https://github.com/ronsse/trellis-ai/discussions) or file an issue.

trellis_ai-0.3.2/LICENSE

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

trellis_ai-0.3.2/Makefile

@@ -0,0 +1,45 @@
+.DEFAULT_GOAL := help
+
+.PHONY: help install install-dev lint format typecheck test check clean build publish-check verify-wheel
+
+help: ## Show this help message
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-15s\033[0m %s\n", $$1, $$2}'
+
+install: ## Install package
+	uv pip install -e .
+
+install-dev: ## Install package with dev dependencies
+	uv pip install -e ".[dev]"
+	python -m pre_commit install
+
+lint: ## Run linting
+	ruff check src/ tests/
+
+format: ## Format code
+	ruff format src/ tests/
+	ruff check --fix src/ tests/
+
+typecheck: ## Run type checking
+	mypy src/
+
+test: ## Run tests
+	pytest tests/ -v
+
+check: lint typecheck test ## Run all checks (lint + typecheck + test)
+
+clean: ## Clean build artifacts
+	rm -rf dist/ build/ *.egg-info .mypy_cache .ruff_cache .pytest_cache
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+
+build: clean ## Build sdist + wheel into dist/
+	python -m build
+
+verify-wheel: build ## Build and inspect wheel contents (sanity-check before tagging)
+	@echo "--- wheel contents ---"
+	@unzip -l dist/*.whl
+	@echo
+	@echo "--- sdist contents ---"
+	@tar -tzf dist/*.tar.gz | head -50
+
+publish-check: build ## Build and run twine check on the artifacts
+	python -m twine check dist/*