Metadata-Version: 2.3
Name: fraise-sdk
Version: 0.1.0b3
Summary: Fraise SDK
Author: Rene Jean Corneille
Author-email: Rene Jean Corneille <14303619+RonsenbergVI@users.noreply.github.com>
Requires-Dist: requests>=2.33.1
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# fraise-sdk (Python)

A Python client for a [Fraise](../../README.md) memory server, plus ready-made
memory tools for agent frameworks.

## Install

```bash
pip install fraise-sdk                 # core client only
pip install 'fraise-sdk[openai]'       # + OpenAI Agents SDK tools
pip install 'fraise-sdk[anthropic]'    # + Claude Agent SDK tools
```

## Client

Two operations, both over the server's single query endpoint:

```python
from fraise_sdk import FraiseClient

with FraiseClient("http://localhost:9876") as fraise:
    fraise.remember("anne loves the color orange", topics=["color"], entities=["anne"])

    result = fraise.recall("anne", "color", top=5)
    for hit in result:
        print(hit.value, hit.score)
```

`recall` returns a `RecallResult` (`.count`, `.hits`, and it iterates/`len()`s
over the hits). Vector search is supported by passing an embedding:

```python
fraise.remember("the kingfisher is electric blue", graph=6, vector=embedding)
hits = fraise.recall(graph=6, vector=embedding)  # seeded only by the vector
```

A recall needs a seed, not a keyword: a vector or a `topics`/`entities` filter
is one on its own, so `fraise.recall(topics=["birds"])` — everything about a
topic — is a query in its own right.

Anything the typed helpers do not cover is reachable through the raw
`fraise.query("recall@3 ...")` escape hatch.

Some queries run but read like a near-miss of a different query — a recall
whose first keyword is also a grammar keyword, e.g. `fraise.recall("since", "7d")`,
one `:` away from a `since:7d` time filter. The server answers them and
attaches a warning; the SDK lists it on `result.warnings` and re-emits it as
a `FraiseWarning`:

```python
import warnings
from fraise_sdk import FraiseWarning

warnings.filterwarnings("ignore", category=FraiseWarning)  # silence wholesale
```

The query shapes that warn (and the neighbouring ones that stay silent) are
catalogued in the query spec, `docs/query-spec.md` § Warnings.

## Embeddings (optional)

Give the client an **embedder** and it encodes text to a vector automatically —
`remember` embeds its value, `recall` embeds its query phrase (or its keywords):

```python
from fraise_sdk import FraiseClient
from fraise_sdk.providers import OpenAIEmbedder   # needs fraise-sdk[openai]

fraise = FraiseClient("http://localhost:9876", embedder=OpenAIEmbedder(dimensions=128))

fraise.remember("the kingfisher is electric blue", graph=6)          # stored with its vector
hits = fraise.recall("small bright bird", graph=6, query="small bright bird")
```

An embedder is anything implementing the `Embedder` ABC (subclass it and define
`embed(text) -> Sequence[float]`) or a plain `callable(text) -> Sequence[float]`,
so a lambda over your own model works too. Per call you can force it with
`embed=True`, skip it with `embed=False`, or override with an explicit `vector=`.
Only OpenAI is provided today — Anthropic has no embeddings API.

## OpenAI Agents tools

`memory_tools(client)` returns a `recall` and a `remember` `FunctionTool` bound
to one memory graph, so the agent decides *what* to store and retrieve:

```python
from agents import Agent, Runner
from fraise_sdk import FraiseClient
from fraise_sdk.integrations.openai_agents import memory_tools

fraise = FraiseClient("http://localhost:9876")
agent = Agent(
    name="Assistant",
    instructions="Remember durable facts the user shares, and recall them when relevant.",
    tools=memory_tools(fraise),
)

result = Runner.run_sync(agent, "My favourite colour is orange. Remember that.")
print(result.final_output)
```

Pass an embedder — `memory_tools(fraise, embedder=OpenAIEmbedder())` — to make
the tools vectorise implicitly: recall and remember encode their text through it
and carry the vector alongside.

See [`examples/openai-agents/`](../../examples/openai-agents) for a complete,
Docker-runnable script.

## Claude Agent SDK tools

The Claude Agent SDK groups tools into an in-process MCP server, so the entry
point is `memory_server(client)`; pair it with `allowed_tools()`:

```python
from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient
from fraise_sdk import FraiseClient
from fraise_sdk.integrations.claude_agents import memory_server, allowed_tools

fraise = FraiseClient("http://localhost:9876")
options = ClaudeAgentOptions(
    system_prompt="Remember durable facts the user shares, and recall them when relevant.",
    mcp_servers={"fraise_memory": memory_server(fraise)},
    allowed_tools=allowed_tools(),
)
```

`memory_server(fraise, embedder=OpenAIEmbedder())` makes the tools vectorise
implicitly, exactly as in the OpenAI integration.

See [`examples/claude-agent-sdk/`](../../examples/claude-agent-sdk) for a
complete, Docker-runnable script.

## Notes & limits

- A fact value is stored inside a single-quoted phrase where every character
  is literal; the SDK escapes apostrophes for you, so `remember("it's blue")`
  stores the text exactly as written.
- Keywords, topics, and entities are single whitespace-free tokens.
- The first vector written to a graph fixes that graph's embedding dimension;
  later writes to the same graph must match it.
- `FraiseClient` defaults to a 30s request timeout (`timeout=` on the
  constructor or on individual `query`/`remember`/`recall` calls overrides
  it); a request that exceeds it raises `FraiseError` naming the timeout,
  distinct from the error raised when the server can't be reached at all.
