Skip to content
Adedev-WPublic

Repository files navigation

Apcone

Python FastAPI FastMCP PostgreSQL Redis Qdrant Docker Tests

Apcone is a tenant-scoped RAG storage service for internal knowledge. It gives your backend or agent stack one place to ingest documents, chunk and embed text, store vectors in Qdrant, search with semantic plus lexical fallback, and expose the same knowledge through HTTP APIs, a Python SDK, CLI commands, and MCP tools.

Use it when you need a small, understandable retrieval layer before building a full agent platform: upload text or PDFs, index them by tenant_id and scope, then search them from an app, script, worker, or MCP-compatible agent.

What It Includes

Area What you get
HTTP API Document ingest, upload, search, chunk read, reindex, delete, job polling, health checks.
Background ingestion Redis/RQ worker pipeline for text and PDF uploads, including OCR routing for scanned PDFs.
Vector storage Qdrant collection management, embeddings with FastEmbed, PostgreSQL metadata and lexical fallback.
MCP server Streamable HTTP MCP endpoint at /mcp/ with authenticated knowledge tools for agents.
Python SDK Async ApconeAsyncClient and ApconeMCPClient wrappers for app and agent code.
CLI Local admin commands for API keys, health, documents, search, and jobs.

Quick Start

uv sync
cp .env.example .env
docker compose up -d postgres redis qdrant
uv run alembic upgrade head
uv run uvicorn app.main:app --reload

Create an API key:

uv run python -m app.cli api-key create --name local-admin --tenant-id default --role admin
export APCONE_API_KEY=<api_key_from_create_output>

Ingest and search a note:

curl -X POST http://127.0.0.1:8000/documents/ingest \
  -H "Authorization: Bearer $APCONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Refund Policy",
    "content": "Refunds are available within 14 days.",
    "source": "policy.md"
  }'

curl -X POST http://127.0.0.1:8000/documents/search \
  -H "Authorization: Bearer $APCONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "refund window", "top_k": 3}'

The API key may be sent as Authorization: Bearer <key> or X-API-Key: <key>. Health endpoints stay public for liveness checks.

Python SDK In 30 Seconds

import asyncio

from apcone_sdk import ApconeAsyncClient, ApconeMCPClient


async def main() -> None:
    api_key = "<apcone_api_key>"

    async with ApconeAsyncClient("http://127.0.0.1:8000", api_key) as client:
        created = await client.ingest_document(
            title="SDK note",
            content="Apcone can search tenant-scoped documents.",
            source="sdk-example",
        )
        results = await client.search_documents("tenant-scoped search")
        print(created.document.id, results[0].content)

    mcp_client = ApconeMCPClient.from_base_url("http://127.0.0.1:8000", api_key)
    mcp_results = await mcp_client.search_documents("tenant-scoped search")
    print(mcp_results.result_count)


asyncio.run(main())

Documentation

Start with docs/getting-started.md if this is your first run. Use docs/http-api.md for endpoint contracts, docs/sdk.md for Python integration, and docs/mcp.md for agent tooling.

Guide Purpose
Documentation index Choose the right reading path.
Getting started Run Apcone locally and perform the first search.
Configuration Understand every important environment variable.
HTTP API Use every endpoint with request and response examples.
Python SDK Integrate Apcone from async Python code.
MCP tools Connect MCP clients and call agent-facing tools.
PDF ingestion Upload PDFs, run workers, and understand OCR routing.
CLI Manage keys, inspect documents, search, and view jobs.
Operations Health checks, troubleshooting, and performance notes.
Architecture How FastAPI, PostgreSQL, Redis, Qdrant, workers, SDK, and MCP fit together.

Local Service Map

With .env.example copied to .env, local ports are:

Service URL
Apcone API http://127.0.0.1:8000
MCP endpoint http://127.0.0.1:8000/mcp/
PostgreSQL 127.0.0.1:5433
Redis 127.0.0.1:6380
Qdrant API/UI http://127.0.0.1:6333
Qdrant dashboard http://127.0.0.1:6333/dashboard
PDF scanner gRPC 127.0.0.1:50051

Run the full test suite with:

uv run pytest

Apcone is intentionally small: clear FastAPI routes, focused services, explicit Pydantic schemas, SQLAlchemy models, and tests around the core API, MCP, SDK, storage, queue, scanner, and CLI behavior.

Contributors

Languages