silica-agent 0.4.0__tar.gz

silica_agent-0.4.0/.claude/hooks/uv-guard.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+"""PreToolUse guard: keep Bash commands on `uv`, the project's only env manager.
+
+Blocks the two things that actually desync the uv-managed .venv / uv.lock:
+  - `pip install` run outside uv (use `uv add` / `uv pip install`)
+  - a bare `pytest` invocation (use `uv run pytest`)
+
+Wired from .claude/settings.json. Exit 2 = block; stderr is shown to the model.
+Run `python3 .claude/hooks/uv-guard.py --selftest` to check the matcher.
+"""
+import json
+import re
+import sys
+
+# Match only at the start of a command *segment* (^, or after ; & | newline), so a
+# literal "pip install" / "pytest" inside a quoted arg or commit message is ignored.
+# ponytail: segment-anchored regex, not a shell lexer; a pipeline like
+# `echo x | pytest` would slip through. Swap in shlex if that ever bites.
+_SEG = r"(?:^|[;&|\n])\s*"
+_PIP = re.compile(_SEG + r"(?:sudo\s+)?(?:python[0-9.]*\s+-m\s+)?pip[0-9.]*\s+install\b")
+_PYTEST = re.compile(_SEG + r"pytest\b")
+
+
+def check(cmd: str) -> str | None:
+    """Return a block reason, or None to allow."""
+    if _PIP.search(cmd):
+        return "pip install desyncs the uv env. Use `uv add <pkg>` (or `uv pip install`)."
+    if _PYTEST.search(cmd):
+        return "Bare pytest may use the wrong interpreter. Use `uv run pytest`."
+    return None
+
+
+def _selftest() -> None:
+    assert check("pip install foo")
+    assert check("pip3 install foo")
+    assert check("python -m pip install foo")
+    assert check("sudo pip install foo")
+    assert check("cd x && pip install foo")
+    assert check("pytest tests/")
+    assert check("cd x && pytest -k thing")
+    assert check("uv add foo") is None
+    assert check("uv pip install foo") is None
+    assert check("uv run pip install foo") is None
+    assert check("uv run pytest -q") is None
+    assert check("git commit -m 'fix pip install docs'") is None
+    assert check("git commit -m 'flaky pytest run'") is None
+    print("uv-guard selftest ok")
+
+
+if __name__ == "__main__":
+    if "--selftest" in sys.argv:
+        _selftest()
+        sys.exit(0)
+    cmd = json.load(sys.stdin).get("tool_input", {}).get("command", "")
+    reason = check(cmd)
+    if reason:
+        print(reason, file=sys.stderr)
+        sys.exit(2)

silica_agent-0.4.0/.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/uv-guard.py\""
+          }
+        ]
+      }
+    ]
+  }
+}

silica_agent-0.4.0/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "silica",
+  "description": "Silica for Claude Code — an Obsidian vault as persistent agent memory, served by a deterministic knowledge-graph engine.",
+  "owner": {
+    "name": "Alessandro Carosia"
+  },
+  "plugins": [
+    {
+      "name": "silica",
+      "source": "./",
+      "description": "Obsidian-vault memory over MCP: recall before answering, capture after learning."
+    }
+  ]
+}

silica_agent-0.4.0/.claude-plugin/plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "silica",
+  "version": "0.1.0",
+  "description": "Obsidian-vault memory for coding agents: deterministic knowledge-graph engine served over MCP (semantic + literal search, gated note writing) with a skill teaching the recall/capture loop.",
+  "author": {
+    "name": "Alessandro Carosia"
+  },
+  "keywords": ["memory", "knowledge-graph", "obsidian", "vault", "mcp"],
+  "mcpServers": {
+    "silica": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--project",
+        "${CLAUDE_PLUGIN_ROOT}",
+        "--with",
+        "mcp",
+        "silica",
+        "mcp"
+      ]
+    }
+  }
+}

silica_agent-0.4.0/.env.example

@@ -0,0 +1,168 @@
+# ============================================================================
+# Silica — configuration
+# Copy this file to .env. Every line is commented out; defaults apply when
+# unset. Ordered from essential to expert: stop reading when you have enough.
+# ============================================================================
+
+
+# ----------------------------------------------------------------------------
+# 1. REQUIRED (the first-run wizard fills these for you)
+# ----------------------------------------------------------------------------
+
+# Main LLM model (litellm format).
+# Examples: openrouter/anthropic/claude-sonnet-4-20250514, openai/gpt-4o,
+#           ollama/llama3.1:8b, lmstudio/qwen/qwen3.5-9b
+# SILICA_MODEL=openrouter/google/gemini-3.5-flash
+
+# Provider preset (derived from SILICA_MODEL when unset).
+# One of: openrouter, lmstudio, ollama, gemini, openai, groq, deepseek,
+# mistral, xai, custom. Silica is tool-driven — with ollama pick a model that
+# supports function-calling (llama3.1, qwen2.5); text-only models will stall.
+# SILICA_PROVIDER=openrouter
+
+# API key for the provider above. ANTHROPIC_API_KEY / OPENAI_API_KEY are only
+# needed when SILICA_MODEL targets that provider directly (litellm reads them).
+# OPENROUTER_API_KEY=
+# ANTHROPIC_API_KEY=
+# OPENAI_API_KEY=
+
+# Obsidian vault path (required for the default fs backend)
+# SILICA_VAULT=/path/to/your/vault
+
+
+# ----------------------------------------------------------------------------
+# 2. CUSTOM ENDPOINT — only with SILICA_PROVIDER=custom
+# ----------------------------------------------------------------------------
+# Any OpenAI-compatible server without a dedicated preset: vLLM, llama.cpp,
+# LocalAI, Jan, or a hosted vendor. Both variables route the "custom" preset.
+
+# SILICA_PROVIDER_BASE_URL=http://localhost:8080/v1
+# SILICA_PROVIDER_API_KEY=
+
+
+# ----------------------------------------------------------------------------
+# 3. RACCOMANDED OPTIONS — embeddings, vault behavior, UI
+# ----------------------------------------------------------------------------
+
+# Embedding model for semantic search and deduplication.
+# Example: qwen3-embedding-4b (LM Studio), text-embedding-3-small (OpenAI)
+# SILICA_EMBEDDING_MODEL=qwen3-embedding-4b
+
+# Embeddings endpoint (defaults to LM Studio local) and its API key
+# SILICA_EMBEDDING_BASE_URL=http://localhost:1234/v1
+# SILICA_EMBEDDING_API_KEY=lm-studio
+
+# Git commit safety net for vault writes: off (default) or auto
+# SILICA_GIT_COMMIT=off
+
+# Inbox folder inside the vault, for staging inbound files. Default: Inbox
+# SILICA_INBOX_DIR=Inbox
+
+# Tool progress display level: off, new, all, verbose
+# SILICA_TOOL_PROGRESS=all
+
+# Show reasoning/thinking blocks from the model (True/False)
+# SILICA_SHOW_THINKING=True
+
+# Startup banner art (True → wordmark, False → plain one-liner)
+# SILICA_SHOW_BANNER=True
+
+# Debug logging on stderr (True/False)
+# SILICA_VERBOSE=False
+
+
+# ----------------------------------------------------------------------------
+# 4. ADVANCED — workers, context, search, PDF
+# ----------------------------------------------------------------------------
+
+# Sub-agent worker model for background tasks (dedup, refiner). If unset,
+# workers fall back to the main model configuration.
+# SILICA_WORKER_MODEL=lmstudio/qwen/qwen3.5-9b
+# SILICA_WORKER_PROVIDER=lmstudio
+# SILICA_WORKER_API_KEY=lm-studio
+
+# Concurrency caps: sub-agent threads (default 3), worker LLM calls (default 4)
+# SILICA_SUBAGENT_MAX_CONCURRENT=3
+# SILICA_WORKER_MAX_CONCURRENT=4
+
+# Context window pin for LOCAL providers (LM Studio, Ollama) only; OpenRouter
+# always uses the provider-reported context_length. Auto-detected if unset.
+# SILICA_MAX_CONTEXT=60000
+
+# Max generation tokens fallback. Default: 65536. Oversized values shrink the
+# OpenRouter provider pool (endpoints with a smaller output cap are dropped).
+# MAX_TOKENS=32768
+
+# Tavily API key (enables /web-search). Bare TAVILY_API_KEY works as fallback.
+# SILICA_TAVILY_API_KEY=
+
+# PDF-to-Markdown converter: mineru (default, silica[pdf] extra), docling, or
+# opendataloader. OCR languages are used by docling only.
+# SILICA_PDF_PROVIDER=mineru
+# SILICA_PDF_OCR_LANG=en,it,fr,de,es
+
+# Driver backend: fs (default, headless filesystem). The Obsidian plugin
+# bridge installs the ws backend live at dial-in; never set ws here.
+# SILICA_BACKEND=fs
+
+# Vault display name (prompt fallback when no vault path is set)
+# SILICA_VAULT_NAME=My Vault
+
+# Domain-pack overlay name, and override dir for recipe packs
+# SILICA_DOMAIN=
+# SILICA_DOMAINS_DIR=
+
+
+# ----------------------------------------------------------------------------
+# 5. RERANKER — optional recall reordering
+# ----------------------------------------------------------------------------
+# A cross-encoder reads query and candidate TOGETHER and reorders recall
+# results. It is not an LLM and not an embedding model, so LM Studio and
+# Ollama cannot serve one. The supported way needs no variables here:
+#
+#     pip install silica[rerank]
+#
+# The cross-encoder then runs inside Silica (~2GB weights on first use).
+# The variables below only point Silica at a reranker you already serve
+# (llama.cpp/Infinity/Jina/Cohere, /rerank protocol); all three must be set
+# and take priority over the in-process one. Local llama.cpp example:
+#   llama-server -m bge-reranker-v2-m3.gguf --reranking --port 1235
+# SILICA_RERANK_BASE_URL=http://localhost:1235/v1
+# SILICA_RERANK_MODEL=bge-reranker-v2-m3
+# SILICA_RERANK_API_KEY=lm-studio
+
+
+# ----------------------------------------------------------------------------
+# 6. EXPERT — similarity thresholds, mindmap, token budgets
+# ----------------------------------------------------------------------------
+# All have safe defaults; override only to tune behavior/cost.
+
+# Dedup: ≥ HIGH → patch existing note; ≤ LOW → new note. Title threshold
+# promotes a pair into the borderline window; THEME is the keep floor.
+# SILICA_SIM_THRESHOLD_HIGH=0.85
+# SILICA_SIM_THRESHOLD_LOW=0.65
+# SILICA_SIM_TITLE_THRESHOLD=0.80
+# SILICA_SIM_THRESHOLD_THEME=0.35
+
+# Candidate notes retrieved per note during dedup scans. Default: 5
+# SILICA_DEDUP_SCAN_K=5
+
+# Language for the co-occurrence graph. Default: auto
+# SILICA_COOCCURRENCE_LANG=auto
+
+# Mindmap (/map <note>): node cap, latent neighbours, wikilink BFS depth
+# SILICA_MINDMAP_MAX_NODES=35
+# SILICA_MINDMAP_LATENT_K=10
+# SILICA_MINDMAP_HOPS=2
+
+# Per-capability generation ceilings and distiller chunking.
+# NOTE: read WITHOUT the SILICA_ prefix (bare names).
+# DEDUP_MAX_TOKENS=1024
+# ORPHAN_MAX_TOKENS=512
+# EXPAND_MAX_TOKENS=4096
+# ENRICH_MAX_TOKENS=256000
+# REFINE_MAX_TOKENS=256000
+# MODEL_CONTEXT_WINDOW=0             # 0 = auto-detect from the model
+# DISTILLER_MAX_TOKENS=0             # 0 = derive from context window
+# DISTILLER_TOKEN_SAFETY_MARGIN=2048
+# DISTILLER_CHUNK_MAX_BYTES=30720    # 30 * 1024

silica_agent-0.4.0/.github/dependabot.yml

@@ -0,0 +1,31 @@
+# Dependabot version updates.
+# Two ecosystems match this repo: uv-managed Python deps (pyproject.toml + uv.lock)
+# and the pinned actions in .github/workflows/release.yml.
+# Commit prefixes (build / ci) map to cliff.toml's "^build|^ci" -> Build & CI section.
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "build"
+      include: "scope"
+    open-pull-requests-limit: 5
+    # Minor/patch bumps arrive as one grouped PR to cut solo-maintainer noise;
+    # majors stay individual so breaking changes are reviewed on their own.
+    groups:
+      python-minor-patch:
+        patterns: ["*"]
+        update-types: ["minor", "patch"]
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "ci"
+      include: "scope"
+    groups:
+      actions:
+        patterns: ["*"]

silica_agent-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,67 @@
+name: release
+
+# Cut a release by pushing a SemVer tag, e.g.:
+#   git tag v0.3.0 && git push origin v0.3.0
+# setuptools-scm reads the tag to stamp the version; git-cliff builds the notes.
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write   # create the GitHub Release
+  id-token: write   # OIDC for PyPI Trusted Publishing (no stored token)
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # full history + tags for setuptools-scm and git-cliff
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - name: Verify built version matches the tag
+        run: ls -1 dist/ && python -c "import pathlib,sys; t='${{ github.ref_name }}'.lstrip('v'); files=[p.name for p in pathlib.Path('dist').glob('*.whl')]; sys.exit(0 if any(t.replace('-','_') in f for f in files) else f'tag {t} not in {files}')"
+
+      - name: Verify the wheel ships runtime assets
+        # Guards the package-data config: a wheel that drops these crashes at
+        # runtime (recipes/prompts/domains are loaded via Path(__file__)).
+        run: |
+          for f in \
+            silica/capabilities/prompts/distiller_prompt.txt \
+            silica/recipes/injector.yaml \
+            silica/domains/codebase.yaml \
+            silica/ui/web/static/index.html \
+            silica/.env.example; do
+            unzip -l dist/*.whl | grep -q "$f" || { echo "MISSING from wheel: $f"; exit 1; }
+          done
+          echo "all runtime assets present in wheel"
+
+      - name: Publish to PyPI
+        # Trusted Publishing via OIDC — the PyPI project must have this repo +
+        # workflow registered as a trusted publisher. No API token in secrets.
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Generate release notes
+        uses: orhun/git-cliff-action@v4
+        id: notes
+        with:
+          config: cliff.toml
+          args: --latest --strip header
+
+      - name: Publish GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          body: ${{ steps.notes.outputs.content }}
+          files: dist/*
+          fail_on_unmatched_files: true

silica_agent-0.4.0/.gitignore

@@ -0,0 +1,190 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+bin/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# setuptools-scm generated version file
+silica/_version.py
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so they can be injected at build time.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nosenvy/
+.noscript/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hatch/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.run/
+tests/fixtures/synthetic_vault/*
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to share your python version with the team.
+#   In that case, comment out the following line.
+#.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, if you're executing a system command that installs a package, you might want to ignore it.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+.pdm-plugins/
+.pdm-python/
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/lincolnloop/layman and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.nosetests/
+.pytest_cache/
+.tox/
+.htmlcov/
+.coverage
+
+# Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Graphs
+graph.html
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Documentation
+/docs/*
+
+# Agents
+/.agents
+CLAUDE.md
+# Ignore local/session Claude state, but track shared harness config.
+/.claude/*
+!/.claude/settings.json
+!/.claude/hooks/
+/memory
+.superpowers
+
+# Vault data (personal)
+.silica/
+.import_linter_cache/
+
+# DB
+ruvector.db
+agentdb.rvf
+
+# Locks
+*.rvf.lock
+CONTEXT.md
+
+# Generated report — line numbers drift; regenerate with /ponytail-debt
+PONYTAIL-DEBT.md
+
+# Golden harness per-run output (only baseline.json is committed)
+evals/golden/metrics.json
+# Stamped per-run benchmark outputs (evals/<bench>/metrics.<run_id>.json)
+evals/*/metrics.*.json
+
+# benchmark vaults + frozen corpora (never committed)
+bench/