synapsekit 0.5.0__tar.gz

synapsekit-0.5.0/.github/DISCUSSION_TEMPLATE/ideas.yml

@@ -0,0 +1,22 @@
+labels: ["idea"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Share your ideas for SynapseKit — new features, integrations, design changes. No idea is too small.
+
+  - type: textarea
+    id: idea
+    attributes:
+      label: The idea
+      description: Describe your idea.
+    validations:
+      required: true
+
+  - type: textarea
+    id: motivation
+    attributes:
+      label: Why?
+      description: What would this enable that isn't possible today?
+    validations:
+      required: false

synapsekit-0.5.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,81 @@
+name: Bug Report
+description: Something isn't working as expected
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for taking the time to report a bug. Please fill in as much detail as possible.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: A clear and concise description of the bug.
+      placeholder: "When I call rag.ask_sync(), it raises ..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: The smallest code snippet that reproduces the issue.
+      render: python
+      placeholder: |
+        from synapsekit import RAG
+
+        rag = RAG(model="gpt-4o-mini", api_key="sk-...")
+        # ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behaviour
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behaviour
+      description: What actually happened? Include the full traceback if applicable.
+      render: shell
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: SynapseKit version
+      placeholder: "0.4.0"
+    validations:
+      required: true
+
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.14.2"
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+      placeholder: "macOS 15.3 / Ubuntu 24.04 / Windows 11"
+    validations:
+      required: false
+
+  - type: textarea
+    id: extras
+    attributes:
+      label: Installed extras
+      description: Which optional packages are installed? (e.g. openai, anthropic, chroma)
+      placeholder: "synapsekit[openai,chroma]"
+    validations:
+      required: false

synapsekit-0.5.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question or Discussion
+    url: https://github.com/SynapseKit/SynapseKit/discussions
+    about: Ask questions and share ideas in Discussions
+  - name: Documentation
+    url: https://synapsekit.github.io/synapsekit-docs/
+    about: Read the full documentation

synapsekit-0.5.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,52 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Have an idea? We'd love to hear it. Before opening, please check if a similar request already exists.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: Describe the problem or limitation you're running into.
+      placeholder: "I'm building a pipeline where I need to... but currently I have to..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: What would you like to see? Include a code sketch if helpful.
+      render: python
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Any other approaches you've thought about or tried?
+    validations:
+      required: false
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - RAG / Pipeline
+        - Agents
+        - Graph Workflows
+        - LLM Provider
+        - Vector Store
+        - Loaders
+        - Output Parsers
+        - Prompt Templates
+        - Observability
+        - Other
+    validations:
+      required: true

synapsekit-0.5.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,36 @@
+## Summary
+
+<!-- What does this PR do? 1-3 sentences. -->
+
+Closes #<!-- issue number -->
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Documentation update
+- [ ] Refactor / internal improvement
+- [ ] Dependency / tooling update
+
+## Changes
+
+<!-- List the key changes made. -->
+
+-
+-
+
+## Testing
+
+- [ ] All existing tests pass (`uv run pytest tests/ -q`)
+- [ ] New tests added for new behaviour
+- [ ] No API keys or secrets in the code
+
+## Documentation
+
+- [ ] Docstrings updated (if public API changed)
+- [ ] [synapsekit-docs](https://github.com/SynapseKit/synapsekit-docs) updated (if new feature)
+- [ ] CHANGELOG.md updated
+
+## Notes for reviewer
+
+<!-- Anything the reviewer should pay particular attention to? -->

synapsekit-0.5.0/.github/profile/README.md

@@ -0,0 +1,57 @@
+<div align="center">
+  <img src="https://raw.githubusercontent.com/SynapseKit/SynapseKit/main/assets/banner.svg" alt="SynapseKit" width="100%"/>
+</div>
+
+<div align="center">
+
+[![PyPI version](https://img.shields.io/pypi/v/synapsekit?color=0a7bbd&label=pypi&logo=pypi&logoColor=white)](https://pypi.org/project/synapsekit/)
+[![Python](https://img.shields.io/badge/python-3.14%2B-blue?logo=python&logoColor=white)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-22c55e)](https://github.com/SynapseKit/SynapseKit/blob/main/LICENSE)
+[![Tests](https://img.shields.io/badge/tests-332%20passing-22c55e?logo=pytest&logoColor=white)]()
+
+</div>
+
+---
+
+**SynapseKit** is an async-native Python framework for building production-grade LLM applications — RAG pipelines, tool-using agents, and graph workflows — with a clean, minimal API.
+
+Built streaming-first from day one. Two hard dependencies. Every abstraction is transparent, composable, and replaceable.
+
+---
+
+### What's inside
+
+| | |
+|---|---|
+| **RAG Pipelines** | Streaming retrieval-augmented generation with 5 text splitters, 7+ document loaders, BM25 reranking, conversation memory |
+| **Agents** | ReAct and native function calling (OpenAI, Anthropic, Gemini, Mistral). 5 built-in tools, fully extensible |
+| **Graph Workflows** | Async DAG pipelines with parallel execution, conditional routing, cycle support, checkpointing, Mermaid export |
+| **9 LLM Providers** | OpenAI, Anthropic, Ollama, Gemini, Cohere, Mistral, Bedrock — one interface, swap without rewriting |
+| **5 Vector Stores** | InMemory, ChromaDB, FAISS, Qdrant, Pinecone — all behind `VectorStore` ABC |
+| **LLM Caching & Retries** | LRU response caching and exponential backoff — opt-in, zero behavior change by default |
+
+### Quick start
+
+```python
+from synapsekit import RAG
+
+rag = RAG(model="gpt-4o-mini", api_key="sk-...")
+rag.add("Your document text here")
+
+async for token in rag.stream("What is the main topic?"):
+    print(token, end="", flush=True)
+```
+
+### Links
+
+- [Documentation](https://synapsekit.github.io/synapsekit-docs/)
+- [Quickstart](https://synapsekit.github.io/synapsekit-docs/docs/getting-started/quickstart)
+- [API Reference](https://synapsekit.github.io/synapsekit-docs/docs/api/llm)
+- [Changelog](https://github.com/SynapseKit/SynapseKit/blob/main/CHANGELOG.md)
+- [Roadmap](https://synapsekit.github.io/synapsekit-docs/docs/roadmap)
+
+### Install
+
+```bash
+pip install synapsekit[openai]    # or [anthropic], [ollama], [all]
+```

synapsekit-0.5.0/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --group dev
+      - run: uv run ruff check src/ tests/
+      - run: uv run ruff format --check src/ tests/
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --group dev
+      - run: uv run mypy
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --group dev
+      - run: uv run pytest tests/ -v
+
+  deptry:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --group dev
+      - run: uv run deptry src/

synapsekit-0.5.0/.gitignore

@@ -0,0 +1,71 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Poetry
+poetry.lock
+
+# pytest
+.pytest_cache/
+.coverage
+htmlcov/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Claude
+.claude/
+CLAUDE.md
+
+
+# Internal docs (not published)
+docs/
+
+# Saved vectorstores
+*.npz

synapsekit-0.5.0/.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.10
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/fpgmaas/deptry
+    rev: 0.22.0
+    hooks:
+      - id: deptry
+        args: [src/]

synapsekit-0.5.0/CHANGELOG.md

@@ -0,0 +1,107 @@
+# Changelog
+
+All notable changes to SynapseKit are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+SynapseKit uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.5.0] — 2026-03-12
+
+### Added
+
+- **Text Splitters** — `BaseSplitter` ABC, `CharacterTextSplitter`, `RecursiveCharacterTextSplitter`, `TokenAwareSplitter`, `SemanticSplitter` (cosine similarity boundaries)
+- **Function calling** — `call_with_tools()` added to `GeminiLLM` and `MistralLLM` (now 4 providers support native tool use)
+- **LLM Caching** — `AsyncLRUCache` with SHA-256 cache keys, opt-in via `LLMConfig(cache=True)`
+- **LLM Retries** — exponential backoff via `retry_async()`, skips auth errors, opt-in via `LLMConfig(max_retries=N)`
+- **Graph Cycles** — `compile(allow_cycles=True)` skips static cycle detection for intentional loops
+- **Configurable max_steps** — `compile(max_steps=N)` overrides the default `_MAX_STEPS=100` guard
+- **Graph Checkpointing** — `BaseCheckpointer` ABC, `InMemoryCheckpointer`, `SQLiteCheckpointer`
+- `CompiledGraph.resume(graph_id, checkpointer)` — re-execute from saved state
+- Adjacency index optimization for `CompiledGraph._next_wave()`
+- `RAGConfig.splitter` — plug any `BaseSplitter` into the RAG pipeline
+- `TextSplitter` alias preserved for backward compatibility
+- 65 new tests (332 total)
+
+### Changed
+
+- `LLMConfig` gains `cache`, `cache_maxsize`, `max_retries`, `retry_delay` fields (all off by default)
+- `pyproject.toml` description updated
+- Version bumped to `0.5.0`
+
+---
+
+## [0.4.0] — 2026-03-11
+
+### Added
+
+- **Graph Workflows** — `StateGraph` fluent builder with compile-time validation and DFS cycle detection
+- **`CompiledGraph`** — wave-based async executor with `run()`, `stream()`, and `run_sync()`
+- **`Node`**, **`Edge`**, **`ConditionalEdge`** — sync and async node functions, static and conditional routing
+- **`agent_node()`**, **`rag_node()`** — wrap `AgentExecutor` or `RAGPipeline` as graph nodes
+- **Parallel execution** — nodes in the same wave run concurrently via `asyncio.gather()`
+- **Mermaid export** — `CompiledGraph.get_mermaid()` returns a flowchart string
+- **`_MAX_STEPS = 100`** guard against infinite conditional loops
+- **`GraphConfigError`**, **`GraphRuntimeError`** — distinct error types for build vs runtime failures
+- 44 new tests (267 total)
+
+### Changed
+
+- **Build tooling** migrated from Poetry to [uv](https://github.com/astral-sh/uv)
+- `pyproject.toml` updated to PEP 621 `[project]` format with hatchling build backend
+- Version bumped to `0.4.0`
+
+---
+
+## [0.3.0] — 2026-03-10
+
+### Added
+
+- **`BaseTool` ABC** — `run()`, `schema()`, `anthropic_schema()`, `ToolResult`
+- **`ToolRegistry`** — tool lookup by name, OpenAI and Anthropic schema generation
+- **`AgentMemory`** — step scratchpad with `format_scratchpad()` and `max_steps` limit
+- **`ReActAgent`** — Thought → Action → Observation loop, works with any `BaseLLM`
+- **`FunctionCallingAgent`** — native OpenAI `tool_calls` and Anthropic `tool_use`, multi-tool per step
+- **`AgentExecutor`** — unified runner with `run()`, `stream()`, `run_sync()`, auto-selects agent type
+- **`call_with_tools()`** — added to `OpenAILLM` and `AnthropicLLM`
+- **Built-in tools**: `CalculatorTool`, `PythonREPLTool`, `FileReadTool`, `WebSearchTool`, `SQLQueryTool`
+- 82 new tests (223 total)
+
+---
+
+## [0.2.0] — 2026-03-08
+
+### Added
+
+- **Loaders**: `PDFLoader`, `HTMLLoader`, `CSVLoader`, `JSONLoader`, `DirectoryLoader`, `WebLoader`
+- **Output parsers**: `JSONParser`, `PydanticParser`, `ListParser`
+- **Vector store backends**: `ChromaVectorStore`, `FAISSVectorStore`, `QdrantVectorStore`, `PineconeVectorStore`
+- **LLM providers**: `OllamaLLM`, `CohereLLM`, `MistralLLM`, `GeminiLLM`, `BedrockLLM`
+- **Prompt templates**: `PromptTemplate`, `ChatPromptTemplate`, `FewShotPromptTemplate`
+- **`VectorStore` ABC** — unified interface for all backends
+- `Retriever.add()` — cleaner public API
+- `RAGPipeline.add_documents(docs)` — ingest `List[Document]` directly
+- `RAG.add_documents()` and `RAG.add_documents_async()`
+- 89 new tests (141 total)
+
+---
+
+## [0.1.0] — 2026-03-05
+
+### Added
+
+- **`BaseLLM` ABC** and `LLMConfig`
+- **`OpenAILLM`** — async streaming
+- **`AnthropicLLM`** — async streaming
+- **`SynapsekitEmbeddings`** — sentence-transformers backend
+- **`InMemoryVectorStore`** — numpy cosine similarity with `.npz` persistence
+- **`Retriever`** — vector search with optional BM25 reranking
+- **`TextSplitter`** — pure Python, zero dependencies
+- **`ConversationMemory`** — sliding window
+- **`TokenTracer`** — tokens, latency, and cost per call
+- **`TextLoader`**, **`StringLoader`**
+- **`RAGPipeline`** — full retrieval-augmented generation orchestrator
+- **`RAG`** facade — 3-line happy path
+- **`run_sync()`** — works inside and outside running event loops
+- 52 tests

synapsekit-0.5.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,35 @@
+# Code of Conduct
+
+## Our Pledge
+
+We as contributors and maintainers pledge to make participation in SynapseKit a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+**Examples of behaviour that contributes to a positive environment:**
+
+- Being respectful and constructive in discussions
+- Welcoming newcomers and helping them get started
+- Accepting feedback gracefully and giving it thoughtfully
+- Focusing on what is best for the community and the project
+
+**Examples of unacceptable behaviour:**
+
+- Harassment, insults, or derogatory comments in any form
+- Personal or political attacks
+- Publishing others' private information without explicit permission
+- Dismissing or belittling contributions, questions, or ideas
+
+## Scope
+
+This Code of Conduct applies in all project spaces — GitHub issues, pull requests, discussions, and any other community forum associated with SynapseKit.
+
+## Enforcement
+
+Instances of unacceptable behaviour may be reported by opening a [private security advisory](https://github.com/SynapseKit/SynapseKit/security/advisories/new) or contacting the maintainer directly. All reports will be reviewed and investigated promptly and fairly.
+
+Maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, issues, and other contributions that do not align with this Code of Conduct, and to ban contributors for behaviours they deem inappropriate.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.