vinc-agent-framework 0.1.0__py3-none-any.whl

vinc_agent_framework/__init__.py

@@ -0,0 +1,9 @@
+"""Vinc for Microsoft Agent Framework.
+
+Design and scope: [[vinc.plan.framework-integration-packages-2026-09-28]].
+"""
+__version__ = "0.1.0"
+
+from .provider import VincContextProvider, create_vinc_tools, record_episode  # noqa: E402
+
+__all__ = ["__version__", "VincContextProvider", "create_vinc_tools", "record_episode"]

vinc_agent_framework/provider.py

@@ -0,0 +1,125 @@
+"""A context provider and read tools that connect an Agent Framework agent to Vinc.
+
+Reading happens on every run, before the model is called. Writing happens only
+when your code calls :func:`record_episode`; the provider never stores the
+conversation.
+"""
+from __future__ import annotations
+
+from typing import Annotated, Any, Iterable, Sequence
+
+from agent_framework import AgentSession, ContextProvider, FunctionTool, SessionContext, tool
+from pydantic import Field
+from vinc_client import (AsyncVincClient, VincQuotaExceeded, VincUnavailable, format_brief,
+                         format_search)
+from vinc_client.context import DEFAULT_MAX_CHARS
+
+DEFAULT_SOURCE_ID = "vinc"
+
+
+def _last_user_text(messages: Sequence[Any]) -> str:
+    """The text of the newest user message; the question the run is about."""
+    for message in reversed(list(messages or [])):
+        if str(getattr(message, "role", "")).lower().endswith("user"):
+            return (getattr(message, "text", "") or "").strip()
+    return ""
+
+
+def create_vinc_tools(client: AsyncVincClient, *,
+                      max_chars: int = DEFAULT_MAX_CHARS) -> list[FunctionTool]:
+    """Two read-only tools the model may call: ``vinc_brief`` and ``vinc_search``.
+
+    Nothing here can write. When Vinc is unavailable or the quota is spent the
+    tool answers with a sentence saying so instead of failing the run.
+    """
+
+    @tool(name="vinc_brief",
+          description="Look up one node in the user's Vinc knowledge graph: a decision, record "
+                      "or concept with its summary, document excerpts and relations. Pass a "
+                      "question or an exact node id such as decision:some-slug.")
+    async def vinc_brief(
+        query: Annotated[str, Field(description="A question, or an exact node id.")],
+    ) -> str:
+        try:
+            return (format_brief(await client.brief(query), max_chars=max_chars)
+                    or "Vinc has no single node for that; try vinc_search.")
+        except (VincUnavailable, VincQuotaExceeded) as exc:
+            return f"Vinc is not available right now ({exc.code}); answer without it."
+
+    @tool(name="vinc_search",
+          description="Search the user's Vinc knowledge graph by text and meaning; returns "
+                      "matching nodes and document passages with their ids.")
+    async def vinc_search(
+        query: Annotated[str, Field(description="What to look for.")],
+        limit: Annotated[int, Field(description="How many matches of each kind.", ge=1,
+                                    le=20)] = 5,
+    ) -> str:
+        try:
+            return (format_search(await client.search(query, limit=limit), max_chars=max_chars,
+                                  limit=limit)
+                    or "No matches in Vinc.")
+        except (VincUnavailable, VincQuotaExceeded) as exc:
+            return f"Vinc is not available right now ({exc.code}); answer without it."
+
+    return [vinc_brief, vinc_search]
+
+
+class VincContextProvider(ContextProvider):
+    """Adds Vinc context to the instructions of every agent run.
+
+    ``before_run`` briefs the newest user message and, when something matched,
+    appends a fenced block marked as data. With ``search_fallback`` (the default)
+    a tie or a miss is widened with a search, so a run costs one call, or two.
+    ``after_run`` does nothing: unlike memory providers that store each turn,
+    this one never writes. Use :func:`record_episode` after a person approved
+    what happened.
+    """
+
+    def __init__(self, client: AsyncVincClient | None = None, *, api_key: str | None = None,
+                 base_url: str | None = None, space: str | None = None,
+                 source_id: str = DEFAULT_SOURCE_ID, search_fallback: bool = True,
+                 max_chars: int = DEFAULT_MAX_CHARS, max_excerpts: int = 3,
+                 min_query_chars: int = 3, expose_tools: bool = False) -> None:
+        super().__init__(source_id)
+        self.client = client or AsyncVincClient(api_key, base_url=base_url, space=space)
+        self._owns_client = client is None
+        self.search_fallback = search_fallback
+        self.max_chars = max_chars
+        self.max_excerpts = max_excerpts
+        self.min_query_chars = min_query_chars
+        self._tools = create_vinc_tools(self.client, max_chars=max_chars) if expose_tools else []
+
+    async def before_run(self, *, agent: Any, session: AgentSession, context: SessionContext,
+                         state: dict[str, Any]) -> None:
+        block = await self.client.get_context(
+            _last_user_text(context.input_messages), search_fallback=self.search_fallback,
+            max_chars=self.max_chars, max_excerpts=self.max_excerpts,
+            min_query_chars=self.min_query_chars)
+        if block:
+            context.extend_instructions(self.source_id, block)
+        if self._tools:
+            context.extend_tools(self.source_id, self._tools)
+
+    async def after_run(self, *, agent: Any, session: AgentSession, context: SessionContext,
+                        state: dict[str, Any]) -> None:
+        # 의도적으로 비어 있다. 대화를 그래프에 쓰지 않는다 — 쓰기는 record_episode 뿐.
+        # 근거: [[decision:framework-integrations-ship-zep-shaped-knowledge-packages-first-2026-09-28]]
+        return None
+
+    async def aclose(self) -> None:
+        """Close the HTTP client if this provider created it."""
+        if self._owns_client:
+            await self.client.aclose()
+
+
+async def record_episode(client: AsyncVincClient, title: str, *, summary: str = "",
+                         about: Iterable[str] = (), date: str | None = None,
+                         domain: str | None = None, tags: Iterable[str] | None = None,
+                         space: str | None = None) -> dict[str, Any]:
+    """Write one Episode about existing concepts or decisions. Needs a ``vinc_sk_`` key.
+
+    Call it after a person approved what the agent did; see
+    :meth:`vinc_client.AsyncVincClient.record_episode`.
+    """
+    return await client.record_episode(title, summary=summary, about=about, date=date,
+                                       domain=domain, tags=tags, space=space)

vinc_agent_framework-0.1.0.dist-info/METADATA

@@ -0,0 +1,80 @@
+Metadata-Version: 2.5
+Name: vinc-agent-framework
+Version: 0.1.0
+Summary: Vinc for Microsoft Agent Framework: bring decisions and records from your knowledge graph into each agent run, without writing anything on its own.
+Project-URL: Homepage, https://vincs.io
+Project-URL: Documentation, https://vincs.io/docs/
+Author: Vinculums
+License-Expression: MIT
+Keywords: agent-framework,context-provider,knowledge-graph,memory,vinc
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: agent-framework-core>=1.8.1
+Requires-Dist: vinc-client<0.2,>=0.1
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# vinc-agent-framework
+
+[Vinc](https://vincs.io) for [Microsoft Agent Framework](https://learn.microsoft.com/agent-framework/). Vinc is a knowledge graph you share with AI: the decisions, records and documents your team wrote, with the reasons attached. This package brings the relevant part of it into each agent run.
+
+## Install
+
+```bash
+pip install vinc-agent-framework
+```
+
+## Add context to every run
+
+```python
+from agent_framework import Agent
+from agent_framework.openai import OpenAIChatClient
+from vinc_agent_framework import VincContextProvider
+
+vinc = VincContextProvider()              # reads VINC_API_KEY; use a vinc_ro_ key
+agent = Agent(
+    client=OpenAIChatClient(),
+    instructions="You review design changes.",
+    context_providers=[vinc],
+)
+await agent.run("Why are our colour tokens stored as OKLCH?")
+```
+
+Before each run the provider looks up the newest user message in Vinc and, when something matches, adds a block to the instructions. The block is marked as data, not instructions, and it cites node ids the model can quote back.
+
+- One call per run; two when the lookup found nothing or several nodes tied, because it then widens with a search (`search_fallback=False` turns that off).
+- If Vinc is unreachable or the daily limit is spent, the run goes on without the block. A wrong key or space raises.
+- For a team's graph pass `space="<team id>"`.
+
+## Let the model look things up
+
+```python
+vinc = VincContextProvider(expose_tools=True)
+```
+
+adds two read-only tools, `vinc_brief` and `vinc_search`. You can also build them yourself with `create_vinc_tools(client)`.
+
+## Writing, on purpose
+
+The provider never stores the conversation: `after_run` does nothing. Record what happened when a person approved it, with a `vinc_sk_` key:
+
+```python
+from vinc_client import AsyncVincClient
+from vinc_agent_framework import record_episode
+
+writer = AsyncVincClient(api_key=WRITE_KEY)
+await record_episode(
+    writer,
+    "Fixed contrast on the dark secondary button",
+    summary="text-secondary now passes 4.5:1 on the dark surface.",
+    about=["decision:tokens-are-oklch"],
+)
+```
+
+## License
+
+MIT

vinc_agent_framework-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+vinc_agent_framework/__init__.py,sha256=txJitioVewiJiEYwFF3l6WCwVlcsDa_IoLtl4CuZZLs,322
+vinc_agent_framework/provider.py,sha256=eO6gK5y-xlbYwQ_qbJ7eMcA_6dfQVe6TiFrcM_eLipY,6186
+vinc_agent_framework/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vinc_agent_framework-0.1.0.dist-info/METADATA,sha256=L2dv4ONa3Cq8-C4fQw7OqWYbrzZyUIlkRck3m08eCtE,2926
+vinc_agent_framework-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+vinc_agent_framework-0.1.0.dist-info/RECORD,,

vinc_agent_framework-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any