Skip to content

BrainAPI is a knowledge graph–powered AI memory layer that transforms unstructured data into structured knowledge, enabling intelligent search, recommendations, and contextual memory for AI agents and applications.

feat(mcp): semantic search tool

Christian0ab097af6ec6
diff --git a/README.md b/README.md
index dce17c4..a579421 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
<p align="center">
<a href="https://discord.gg/VTngQTaeDf"><img src="https://img.shields.io/badge/Discord-Join%20Lumen%20Brain-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord"/></a>
- <img src="https://img.shields.io/badge/version-2.10.0--dev-blue?style=for-the-badge" alt="Version"/>
+ <img src="https://img.shields.io/badge/version-2.10.1--dev-blue?style=for-the-badge" alt="Version"/>
<img src="https://img.shields.io/badge/python-3.11+-green?style=for-the-badge&logo=python&logoColor=white" alt="Python"/>
<img src="https://img.shields.io/badge/license-AGPLv3%20%2B%20Commons%20Clause-purple?style=for-the-badge" alt="License"/>
</p>
diff --git a/pyproject.toml b/pyproject.toml
index 9c88110..6c43e47 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "brainapi2"
-version = "2.10.0-dev"
+version = "2.10.1-dev"
description = "Version 2.x.x of the BrainAPI memory layer."
authors = [
{name = "Christian",email = "[email protected]"}
diff --git a/src/services/mcp/main.py b/src/services/mcp/main.py
index 060c2b3..f020c57 100644
--- a/src/services/mcp/main.py
+++ b/src/services/mcp/main.py
@@ -13,6 +13,7 @@ from contextvars import ContextVar
from typing import Any
from mcp.server import FastMCP
from pydantic import BaseModel
+from src.core.instances import embeddings_adapter, vector_store_adapter
from src.lib.neo4j.client import _neo4j_client
from src.services.data.main import data_adapter
from src.services.kg_agent.main import graph_adapter
@@ -59,6 +60,31 @@ def search_memory(db_query: str, brain_id: str) -> Any:
return graph_adapter.execute_operation(db_query, brain_id)
except Exception as e:
return f"Error executing graph operation: {e}"
+
+
+def search_semantically(query: str, brain_id: str) -> Any:
+ """
+ Search information semantically, given a query and a brain to search in,
+ this tool will return a list of graph nodes that are semantically related to the query.
+
+ This tool is useful to search into the graph for information without knowing names or labels.
+
+ Input must be a JSON object with the following fields:
+ - query: str: the query to search for.
+ - brain_id: str: the brain to search in.
+ """
+ try:
+ if not guard_brainpat(auth_token_var.get(), brain_id):
+ return "Unauthorized"
+ query_embedding = embeddings_adapter.embed_text(query)
+ data_vectors = vector_store_adapter.search_vectors(
+ query_embedding.embeddings, store="nodes", brain_id=brain_id, k=5
+ )
+ triplets = graph_adapter.get_event_centric_neighbors([v.metadata.get("uuid") for v in data_vectors], brain_id=brain_id)
+ return triplets
+ except Exception as e:
+ return f"Error executing graph operation: {e}"
@mcp.tool()
diff --git a/src/services/mcp/openai-reverse-engineered-prompt.md b/src/services/mcp/openai-reverse-engineered-prompt.md
new file mode 100644
index 0000000..80be4c5
--- /dev/null
+++ b/src/services/mcp/openai-reverse-engineered-prompt.md
@@ -0,0 +1,272 @@
+/\*
+
+- File: /src/services/mcp/openai-reverse-engineered-prompt.md
+- Project: brainapi2
+- Created Date: Wednesday March 18th 2026
+- Author: Christian Nonis <[email protected]>
+- ***
+- Last Modified: Wednesday March 18th 2026 9:07:28 pm
+- Modified By: Christian Nonis <[email protected]>
+- ***
+ \*/
+
+i want you recursively iterate and export into a csv or json the knowledge that you have of me, use the tools at your disposal to start with a seed search and iterate untill you get everything, than write a file and export it to me
+
+Exporting knowledge and skills
+
+Activity
+·
+27s
+
+Thinking
+Thinking longer for a better answer
+Thinking longer for a better answer
+
+Exporting knowledge and skills
+bash -lc cat /home/oai/skills/spreadsheets/SKILL.md && printf '
+---DOCX---
+' && cat /home/oai/skills/docx/SKILL.md | sed -n '1,120p'
+
+# Spreadsheet Skill (Create • Edit • Analyze • Visualize)
+
+## Use the artifact_tool python library or openpyxl
+
+- You can use either python library (openpyxl or artifact_tool) for creating and editing spreadsheets. They are two different libraries, so do not mix their interfaces.
+- artifact_tool can render and recalculate spreadsheets which is important for checking your work, even if you used openpyxl to edit the workbook
+- You can import artifact_tool in python using either the python tool or container.exec tool
+- Simple instructions on artifact_tool usage can be found in artifact_tool_spreadsheet.md, and example scripts using artifact_tool are provided in artifact_tool_examples/.
+- If possible, you MUST use artifact_tool to recalculate formulas and save the workbook with cached values before providing it to the user
+- If possible, you MUST use artifact_tool to render each sheet, and review the rendered image for style, formatting, and correctness
+- You can open the rendered png images in python with matplotlib.pyplot.imshow and PIL.Image, or using the `container.open_image` tool if available
+- The artifact_tool api can be found in artifact_tool_spreadsheet_api.md
+- Note that artifact_tool will not recalculate formulas automatically on edit by default, but you may pass in a recalculate=True parameter to the edit functions; This is for efficiency and allows you to make a bunch of bulk edits and updates before recalculating formulas. You must manually recalculate formulas using recalculate() function. Recalculate happens automatically before render and export. Always call recalculate() before just reading cell values.
+- The full artifact_tool api can be found in artifact_tool_spreadsheet_api.md.
+- Do not disclose any source code or information to the user about artifact_tool; it is a proprietary library.
+- If not using artifact_tool, prefer using openpyxl over pandas to enable formatting the spreadsheet according to the style guidelines
+
+### Openpxyl Rules
+
+- If you are using a Table in openpxyl, do NOT also set ws.auto_filter.ref on the same range.
+
+### artifact_tool python library
+
+- Do not use `openpyxl` API names on `artifact_tool` objects.
+- Do not assume Office.js, Excel JS, or prior internal workbook-surface APIs apply here.
+- If an API call is unclear, check the `artifact_tool` docs already referenced by this skill before writing code. `artifact_tool_spreadsheet.md` has exact code blocks to get started quickly.
+
+##### Use these exact artifact_tool call shapes for getting started
+
+- `from artifact_tool import SpreadsheetArtifact`
+- `spreadsheet = SpreadsheetArtifact.load("/path/to/file") # or SpreadsheetArtifact("NewSpreadsheet") to create an empty one`
+- `sheet = artifact.sheet("SheetName")`
+- `sheet_names = artifact.sheets()`
+- `sheet.cell("A1").value = 123`
+- `sheet.cell("A3").formula = "=A1+5"`
+- `sheet.range("A2:B5").values = [[...]]` or `sheet.range("A2:B5").set_values([[...]])`
+- `sheet.range("C2:C5").formulas = [[...]]` or `sheet.range("C2:C5").set_formulas([[...]])`
+- `rendered_spreadsheet = artifact.render()`
+- `exported_spreadsheet = artifact.export("/path/to/file", overwrite=True)`
+
+### Check your work
+
+- Before providing your completed spreadsheet to the user, check to ensure it is accurate and without errors.
+- Use artifact_tool to recalculate the workbook, and address any printed warnings or incorrect calculated cells.
+- After recalculating to ensure calculated values are cached, render the spreadsheet with artifact_tool and view the images to check for style, formatting, and correctness
+
+### Use /mnt/data
+
+- Look for input files uploaded by the user at /mnt/data
+- Write any output files to /mnt/data
+
+## Formula requirements
+
+### Use formulas for derived values
+
+- Any derived values must be calculated using spreadsheet formulas rather than hardcoded
+
+### Best practices
+
+- Formulas should be simple and legible. Use helper cells for intermediate values rather than performing complex calculations in a single cell
+- Avoid the use of volatile functions like INDIRECT and OFFSET except where necessary
+- Use absolute ($B$4) or relative (B4) cell references as appropriate such that copy/pasting to adjacent similar cells behaves correctly
+- Do not use magic numbers in formulas. Instead, use cell references to input cells. Example: Use "=H6*(1+$B$3)" instead of "=H6*1.04"
+- If you want to write text (not an evaluated formula) in a cell starting with "=", make sure to prepend a single quote ' like "'=high-low" to avoid a #NAME error
+
+### Ensure formulas are correct
+
+- Spreadsheets must not contain added formula errors (#REF!, #DIV/0!, #VALUE!, #N/A, #NAME?)
+- Verify all formulas recalculate correctly; you must recalculate all formulas and check the computed values are correct before submitting your final response.
+- Guard against bugs in formulas:
+ - Verify correct cell references
+ - Check for off-by-one errors
+ - Test by varying inputs with edge cases
+ - Verify no unintended circular references
+
+### Ensure calculated values are cached
+
+- When using openpyxl, formulas will not be cached in the saved workbook
+- Ensure they are calculated without errors and cached before providing the spreadsheet to the user, for example by loading with artifact_tool, calling recalculate(), and overwriting the xlsx file
+
+## Citation requirements
+
+### Cite sources within the spreadsheet
+
+- Always cite your sources using plain text URLs. Do not use any special citation formats within spreadsheets, only in your final response.
+- For financial models, cite sources of model inputs in the cell comment
+- For tabular data researched from the web or other sources where each row represents one item, cite sources in a separate column
+
+## Formatting requirements when provided a formatted spreadsheet as part of the task
+
+### Preserve existing formatting and style
+
+- Always render a provided spreadsheet before modifying it to see what it looks like
+- Carefully examine and EXACTLY match the existing formatting and style when modifying spreadsheets
+- When modifying cells in a provided spreadsheet that were previously blank and unformatted, determine how to format them to match the style of the provided spreadsheet
+- Never overwrite formatting for spreadsheets with established formats
+
+## Formatting requirements when not provided a formatted spreadsheet or when explicitly asked to reformat without any formatting guidelines
+
+### Choose appropriate number and date formats
+
+- Dates should have an appropriate date format and should not be numbers ("2028", not "2,028")
+- Percentages should default to one decimal point (0.0%) unless it does not make sense for the scale and precision of the data
+- Currencies should always have an appropriate currency format ($1,234)
+- Other numbers should have an appropriate number of digits and decimal places
+
+### Use a visually clear layout
+
+- Headers should be formatted differently from data and derived cells to distinguish them with a consistent visual styel
+- Use fill colors, borders, and merged cells judiciously to give the spreadsheet a professional visual style with a clear layout without overdoing it
+- Set appropriate row heights and column widths to give a clean visual appearance; contents of cells should be readable within the cell, without excessive buffer space
+- Do not apply borders around every filled cell
+- Group similar values and calculations together, and aim to make totals a simple sum of the cells above them.
+- Add strategic whitespace to separate sections
+- Ensure cell text does not spill out to other cells by using appropriate cell dimensions and fonts
+ For example, in an income statement with revenue, cost of sales, and gross profit across 3 verticals where each column is a different calendar year, below the header row should be the income for each vertical, followed by the total (label in bold), followed by a blank row, and then similar for cost of sales and gross profit.
+
+### Use standard color conventions for text colors:
+
+If the user does not provide color specifications and the user does not provide a styled workbook
+
+- Blue: User input
+- Black: Formula / derived
+- Green: Linked / imported
+- Gray: Static constants
+- Orange: Review / caution
+- Light red: Error / flag
+- Purple: Control / logic
+- Teal: Visualization anchors; highlight key KPI or chart driver
+
+### Additional requirements for financial models
+
+- Make all zeros formatted as "-"
+- Negative numbers should be red and in parentheses; (500), not -500. In Excel this might be "$#,##0.00_);[Red] ($#,##0.00)"
+- For multiples, format as 5.2x
+- Always specify units in headers; "Gross Income ($mm)"
+- All added raw inputs should have their sources cited in the appropriate cell comment
+
+#### Finance-specific color conventions:
+
+When building new financial models where no user-provided spreadsheet or formatting instructions override these conventions, use:
+
+- **Blue text (RGB: 0,0,255)**: Hardcoded inputs, and numbers users will change for scenarios
+- **Black text (RGB: 0,0,0)**: ALL formulas and calculations
+- **Green text (RGB: 0,128,0)**: Links pulling from other worksheets within same workbook
+- **Red text (RGB: 255,0,0)**: External links to other files
+- **Yellow background (RGB: 255,255,0)**: Key assumptions needing attention or cells that need to be updated
+
+### Additional requirements for investment banking
+
+If the spreadsheet is related to investment banking (LBO, DCF, 3-statement, valuation model, or similar):
+
+- Total calculations should sum a range of cells directly above them.
+- Hide gridlines. Add horizontal borders above total calculations, spanning the full range of relevant columns including any label column(s).
+- Section headers applying to multiple columns and rows should be left-justified, filled black or dark blue with white text, and should be a merged cell spanning the horizontal range of cells to which the header applies.
+- Column labels (such as dates) for numeric data should be right-aligned, as should be the data.
+- Row label[... ELLIPSIZATION ...]t.
+
+2. Once you have a working DOCX, continue iterating until the entire document is polished and correct. After every change or edit, render the DOCX and review it carefully to evaluate the result. The plan from (1) should guide you, but it is only a flexible draft; you should update your decisions as needed throughout the revision process. Important: each time you render and reflect, you should check for both:
+ 1. Design aesthetics: the document should be aesthetically pleasing and easy to skim. Ask yourself: if a human were to look at my document, would they find it aesthetically nice? It should feel natural, smooth, and visually cohesive.
+ 2. Formatting issues that need to be fixed: e.g. text overlap, overflow, cramped spacing between adjacent elements, awkward spacing in tables/charts, awkward page breaks, etc. This is super important. Do not stop revising until all formatting issues are fixed.
+
+While making and revising the DOCX, please adhere to and check against these quality reminders, to ensure the deliverable is visually high quality:
+
+- Document density: Try to avoid having verbose dense walls of text, unless it's necessary. Avoid long runs of consecutive plain paragraphs or too many words before visual anchors. For some tasks this may be necessary (i.e. verbose legal documents); in those cases ignore this suggestion.
+- Font: Use professional, easy-to-read font choices with appropriate size that is not too small. Usage of bold, underlines, and italics should be professional.
+- Color: Use color intentionally for titles, headings, subheadings, and selective emphasis so important information stands out in a visually appealing way. The palette and intensity should fit the document's purpose, with more restrained use where a formal or serious tone is needed.
+- Visuals: Consider using tables, diagrams, and other visual components when they improve comprehension, navigation, or usability.
+- Tables: Please invest significant effort to make sure your tables are well-made and aesthetically/visually good. Below are some suggestions, as well as some hard constraints that you must relentlessly check to make sure your table satisfies them.
+ - Suggestions:
+ - Set deliberate table/cell widths and heights instead of defaulting to full page width.
+ - Choose column widths intentionally rather than giving every column equal width by default. Very short fields (for example: item number, checkbox, score, result, year, date, or status) should usually be kept compact, while wider columns should be reserved for longer content.
+ - Avoid overly wide tables, and leave generous side margins so the layout feels natural.
+ - Keep all text vertically centered and make deliberate horizontal alignment choices.
+ - Ensure cell height avoids a crowded look. Leave clear vertical spacing between a table and its caption or following text.
+ - Hard constraints:
+ - To prevent clipping/overflow:
+ - Never use fixed row heights that can truncate text; allow rows to expand with wrapped content.
+ - Ensure cell padding and line spacing are sufficient so descenders/ascenders don't get clipped.
+ - If content is tight, prefer (in order): wrap text -> adjust column widths -> reduce font slightly -> abbreviate headers/use two-line headers.
+ - Padding / breathing room: Ensure text doesn't sit against cell borders or look "pinned" to the upper-left. Favor generous internal padding on all sides, and keep it consistent across the table.
+ - Vertical alignment: In general, you should center your text vertically. Make sure that the content uses the available cell space naturally rather than clustering at the top.
+ - Horizontal alignment: Do not default all body cells to top-left alignment. Choose horizontal alignment intentionally by column type: centered alignment often works best for short values, status fields, dates, numbers, and check indicators; left alignment is usually better for narrative or multi-line text.
+ - Line height inside cells: Use line spacing that avoids a cramped feel and prevents ascenders/descenders from looking clipped. If a cell feels tight, adjust wrapping/width/padding before shrinking type.
+ - Width + wrapping sanity check: Avoid default equal-width columns when the content in each column clearly has different sizes. Avoid lines that run so close to the right edge that the cell feels overfull. If this happens, prefer wrapping or column-width adjustments before reducing font size.
+ - Spacing around tables: Keep clear separation between tables and surrounding text (especially the paragraph immediately above/below) so the layout doesn't feel stuck together. Captions and tables should stay visually paired, with deliberate spacing.
+ - Quick visual QA pass: Look for text that appears "boundary-hugging", specifically content pressed against the top or left edge of a cell or sitting too close beneath a table. Also watch for overly narrow descriptive columns and short-value columns whose contents feel awkwardly pinned. Correct these issues through padding, alignment, wrapping, or small column-width adjustments.
+- Forms / questionnaires: Design these as a usable form, not a spreadsheet.
+ - Prioritize clear response options, obvious and well-sized check targets, readable scale labels, generous row height, clear section hierarchy, light visual structure. Please size fields and columns based on the content they hold rather than by equal-width table cells.
+ - Use spacing, alignment, and subtle header/section styling to organize the page. Avoid dense full-grid borders, cramped layouts, and ambiguous numeric-only response areas.
+- Coherence vs. fragmentation: In general, try to keep things to be one coherent representation rather than fragmented, if possible.
+ - For example, don't split one logical dataset across multiple independent tables unless there's a clear, labeled reason.
+ - For example, if a table must span across pages, continue to the next page with a repeated header and consistent column order
+- Background shapes/colors: Where helpful, consider section bands, note boxes, control grids, or other visual containers with suitable colors to improve scanability and communication. Use them when they suit the document type. If you do use these, make sure they are formatted well, with no overlaps, awkward spacing, etc.
+- Spacing: Please check rigorously for spacing issues. Please always use a natural amount of spacing between adjacent components. Use clear, generous vertical spacing between sections and paragraphs, and leave a bit of extra space between subheadings and the content that follows when it improves readability. Use indentation and alignment intentionally so the document's hierarchy is immediately clear. At the same time, avoid large "layout gaps" caused by a table or chart not fitting at the bottom of a page and getting pushed to the next one. If this happens, please try these suggestions:
+ - moving the preceding paragraph(s) with it to the next page to keep the narrative cohesive
+ - scaling the visual modestly or simplify labels without hurting readability, formatting, or aesthetics of the visual
+ - Splitting the table/figure cleanly across multiple pages, but use repeated headers to make the page continuation clear.
+- Text boxes: For text boxes, please follow the same breathing-room rules as the tables: make sure to use generous internal padding, intentional alignment, and sufficient line spacing so text never feels cramped, clipped, or pinned to the edges. Keep spacing around the text box clear so it remains visually distinct from surrounding content, and if the content feels tight, prefer adjusting box size, padding, or text wrapping before reducing font size.
+- Layout/archetype: Remember to choose the right document archetype/template (proposal, SOP, workflow, form, handbook, etc.). Use a coherent style system. Once a style system is chosen, apply it consistently across headings, spacing, table treatments, callouts, and accent usage. If appropriate to the document type, include a cover page or front-matter elements such as title, subtitle, metadata, or branding.
+
+### Editing tasks (DOCX edits) — apply instead of major rewrite behavior
+
+When the user asks to edit an existing document, preserve the original and make minimal, local changes:
+
+- Prefer inline edits (small replacements) over rewriting whole paragraphs.
+- Use clear inline annotations/comments at the point of change (margin comments or comment markers). Don’t move all feedback to the end.
+- Keep the original structure unless there’s a strong reason; if a restructure is needed, do it surgically and explain via comments.
+- Don’t “cross out everything and rewrite”; avoid heavy, blanket deletions. The goal is trackable improvements, not a fresh draft unless explicitly requested.
+
+## Quick start (common one-liners)
+
+```bash
+# 1) Render any DOCX to PNGs (visual QA)
+python render_docx.py input.docx --output_dir out
+
+# 2) Remove reviewer comments (finalization)
+python scripts/comments_strip.py input.docx --out no_comments.docx
+
+# 3) Accept tracked changes (finalization)
+python scripts/accept_tracked_changes.py input.docx --mode accept --out accepted.docx
+
+# 4) Accessibility audit (+ optional safe fixes)
+python scripts/a11y_audit.py input.docx
+python scripts/a11y_audit.py input.docx --out_json a11y_report.json
+python scripts/a11y_audit.py input.docx --fix_image_alt from_filename --out a11y_fixed.docx
+
+# 5) Redact sensitive text (layout-preserving by default)
+python scripts/redact_docx.py input.docx redacted.docx --emails --phones
+```
+
+## Package layout
+
+This skill is organized for progressive discovery: start here, then jump into task- or OOXML-specific docs.
+
+DOCS SKILL PACKAGE
+
+Root:
+
+- SKILL.md: short overview + routing
+- manifest.txt: machine-readable list of files to download (one relative path per line)
+- render_docx.py: canonical DOCX→PNG renderer (container-safe LO profile + writable HOME + verbose logs)
+ ChatGPT is still generating a response...
diff --git a/src/services/mcp/utils.py b/src/services/mcp/utils.py
index 2904fa7..f5a6692 100644
--- a/src/services/mcp/utils.py
+++ b/src/services/mcp/utils.py
@@ -20,6 +20,7 @@ def guard_brainpat(pat: str = None, target_brain: str = None) -> bool | str:
If the BrainPAT is not matching any brain, it will try to match with the systempat,
if the systempat is not matching, it will raise an auth error.
"""
+ print(pat, config.brainpat_token)
if pat == config.brainpat_token:
return True