Metadata-Version: 2.4
Name: june-openai-agents
Version: 0.1.0
Summary: Give your OpenAI Agents SDK agent a June memory — wrap any Session to mirror conversations into a searchable, cited June knowledge canvas, add a memory-search tool, and backfill existing session databases.
Author-email: Junemind <access@januraine.ai>
License-Expression: MIT
Project-URL: Homepage, https://june.januraine.ai
Project-URL: Source, https://github.com/Junemind/june-openai-agents
Project-URL: Releases, https://github.com/Junemind/June_releases
Keywords: openai-agents,agents-sdk,agent-memory,session,knowledge-graph,june
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai-agents>=0.6
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

# june-openai-agents

**Give your OpenAI Agents SDK agent a June memory.** The SDK's Sessions are
built for *resuming* a conversation — long-term, searchable memory is left
as an exercise. This package closes the loop on both sides against
[Junê](https://june.januraine.ai): conversations flow into a **local-first,
searchable, cited knowledge graph** as your agent runs, and the agent can
search that memory back while answering.

```
Runner ──▶ JuneSession (wraps your Session) ──▶ June canvas ◀── june_memory_tool
             writes as the agent runs             graph · cited     the agent reads back
```

## Write side — wrap the session you already use

```bash
pip install june-openai-agents
```

```python
from agents import Agent, Runner, SQLiteSession
from june_openai_agents import JuneSession

session = JuneSession(
    SQLiteSession("thread-42", "conversations.db"),   # any Session works
    june_url="http://127.0.0.1:8799",     # the Junê desktop app's local engine
    api_key="local",
    canvas="agent-memory",
    state_file=".june_oai_pending.json",  # retry buffer, survives restarts
)
result = await Runner.run(agent, "hello", session=session)
```

`JuneSession` satisfies the SDK's runtime-checkable `Session` protocol —
attributes included — so the Runner can't tell the difference. Every
operation delegates to your real session first; each batch of new items then
mirrors to June while they're still live dicts. **Fail-soft:** June being
down never breaks a run — unmirrored items go to a persisted pending buffer
and flush on the next add (`strict=True` raises instead). Tool-call frames,
reasoning items and empty turns are filtered out — only conversation becomes
memory. `JuneSession.from_env(inner)` reads the same `JUNE_BASE_URL` /
`JUNE_API_KEY` / `JUNE_CANVAS` env vars as june-mcp.

## Read side — one tool and the agent can recall

```python
from agents import Agent
from june_openai_agents import june_memory_tool

agent = Agent(
    name="assistant",
    instructions="Use june_memory_search before answering questions about "
                 "prior conversations or saved knowledge.",
    tools=[june_memory_tool()],           # env-var config by default
)
```

The tool searches the same canvas the session writes into and returns
matched knowledge as plain lines the model can ground on.

## Backfill — history your app already saved

```bash
june-openai-agents sync --db conversations.db     # one incremental pass
june-openai-agents watch --db conversations.db    # keep syncing (Ctrl+C stops)
june-openai-agents doctor --db conversations.db   # PASS/FAIL the setup
```

Discovery is metadata-only SQL (which session ids exist); **content is
always read through the SDK's own `SQLiteSession`**, so the SDK decodes its
stored items — never us. Every pass is incremental via a per-item ledger;
re-running never duplicates, and even a forced re-push is folded by June's
read-side dedup.

## What you get on the June side

The canvas behaves like any other: search it, ask cited questions over it in
the Junê app, and point [june-mcp](https://pypi.org/project/june-mcp) at the
same canvas so Claude can answer over your agent's entire history.

Part of a family: [june-langgraph](https://pypi.org/project/june-langgraph)
(LangGraph checkpointers) and [june-adk](https://pypi.org/project/june-adk)
(Google ADK's MemoryService) do the same for their frameworks.

## License

MIT. The Junê engine itself is a separate, closed-source product — this
connector is the open part, by design.
