add_document

Instructions

Implementation Reference

• src/foundry_reverse/knowledge.py:114-131 (handler)

  Core handler that adds a document to an index. Retrieves the index by name, computes an embedding via Ollama, creates a Document dataclass with UUID, text, metadata, and embedding, appends it to the index, persists to disk, and returns status.

  async def add_document(
      index_name: str,
      text: str,
      metadata: dict[str, Any] | None = None,
  ) -> dict[str, Any]:
      idx = _indexes.get(index_name)
      if idx is None:
          raise ValueError(f"Index '{index_name}' not found. Create it first.")
      embedding = await oc.embeddings(idx.embed_model, text)
      doc = Document(
          id=str(uuid.uuid4()),
          text=text,
          metadata=metadata or {},
          embedding=embedding,
      )
      idx.documents.append(doc)
      _save()
      return {"status": "added", "id": doc.id, "index": index_name}

• src/foundry_reverse/knowledge.py:24-29 (schema)

  Document dataclass schema defining the structure of a stored document (id, text, metadata, embedding).

  @dataclass
  class Document:
      id: str
      text: str
      metadata: dict[str, Any]
      embedding: list[float]

• src/foundry_reverse/server.py:304-326 (registration)

  MCP tool registration using @mcp.tool decorator with name='add_document'. Defines parameters (index_name, text, metadata) and delegates to kn.add_document().

  @mcp.tool(
      name="add_document",
      description=(
          "Add a text document to a knowledge index. "
          "The text is embedded automatically using the index's embedding model."
      ),
  )
  async def add_document(
      index_name: str,
      text: str,
      metadata: dict[str, Any] | None = None,
  ) -> dict[str, Any]:
      """
      Args:
          index_name: The target index name (must be created first).
          text: Document text to store and embed.
          metadata: Optional key-value metadata to attach to the document.
      """
      return await kn.add_document(
          index_name=index_name,
          text=text,
          metadata=metadata,
      )

• src/foundry_reverse/knowledge.py:44-81 (helper)

  Persistence helpers: _save() serializes all indexes (including documents with embeddings) to JSON, _load() deserializes on startup.

  def _save() -> None:
      data = {}
      for idx_name, idx in _indexes.items():
          data[idx_name] = {
              "embed_model": idx.embed_model,
              "documents": [
                  {
                      "id": d.id,
                      "text": d.text,
                      "metadata": d.metadata,
                      "embedding": d.embedding,
                  }
                  for d in idx.documents
              ],
          }
      STORE_PATH.write_text(json.dumps(data))
  
  
  def _load() -> None:
      if not STORE_PATH.exists():
          return
      data = json.loads(STORE_PATH.read_text())
      for idx_name, idx_data in data.items():
          docs = [
              Document(
                  id=d["id"],
                  text=d["text"],
                  metadata=d["metadata"],
                  embedding=d["embedding"],
              )
              for d in idx_data["documents"]
          ]
          _indexes[idx_name] = Index(
              name=idx_name,
              embed_model=idx_data["embed_model"],
              documents=docs,
          )