Senora-dev/aquifer-ai: 오픈 소스 in-VPC 컨텍스트 레이크 (Context Lake)

오픈 소스인 in-VPC 컨텍스트 레이크 (Context Lake) — 개발자 포털도 아니고 추론 엔진도 아닌, **AI 에이전트를 위한 중립적인 인프라 (infrastructure)**입니다. Aquifer는 헤드리스(headless) 방식으로 작동합니다. 엔지니어링 컨텍스트(GitHub 우선)를 OpenSearch 벡터 스토어(vector store)로 집계하고, AI 에이전트가 직접 쿼리할 수 있는 표준 MCP API를 노출합니다. 모든 과정은 귀하의 자체 VPC 내부에서 이루어지며, 단일 CDK 스택으로 배포 가능합니다.

에이전트가 사용자이며, Aquifer는 중립을 유지합니다. UI는 전혀 없습니다. 또한 판결도 내리지 않습니다. Aquifer는 객관적이고 조직화된 컨텍스트(엔티티, 관계, 키)를 제공하고, 에이전트가 직접 추론하도록 합니다. 우리는 의사 결정자가 아닌, 업계 최고의 검색 및 검색 (Search & Retrieval) 레이어가 되는 것을 목표로 합니다.

AI 에이전트의 성능은 그들이 접근할 수 있는 컨텍스트의 품질에 달려 있습니다. Aquifer는 귀하의 엔지니어링 소스에 대한 단일하고 신뢰할 수 있는 검색 및 검색 (Search & Retrieval) 레이어입니다. 이는 데이터를 수집(ingest)하고, 임베딩(embed)하며, 수집 시점에 중립적이고 객관적인 메타데이터(service:billing-api 및 jira_key:PROJ-400와 같은 타입화된 엔티티, 그리고 depends_on / references / part_of와 같은 사실적 관계)를 추출하여 쿼리 가능한 필드로 인덱싱합니다. 그러면 에이전트는 스스로 추론하는 데 필요한 정확한 컨텍스트를 검색할 수 있습니다 (예: 배포 여부를 결정하기 전에 해당 서비스와 관련된 모든 정보를 수집). 이 과정에서 데이터는 네트워크를 전혀 벗어나지 않으며, 귀하의 Bedrock 이외의 외부 AI 처리도 발생하지 않습니다.

Aquifer는 결론을 도출하거나 가치 판단을 내리지 않습니다. 점수를 매기거나, 위험도에 따라 순위를 정하거나, "배포할 수 있나요?"라는 질문에 답하지 않습니다. Aquifer는 사실을 반환하며, 결정은 에이전트가 합니다.

상태: 기능적인 중립적 컨텍스트 레이크 (Context Lake)입니다. MCP를 통해 컨텍스트를 수집, 임베딩 및 제공합니다. 시맨틱 인덱싱(semantic indexing, before_ingest 훅 내)은 소스별 모듈식 프롬프트 레지스트리를 통해 객관적인 엔티티와 관계를 추출하고 이를 쿼리 가능한 필드로 인덱싱합니다. 또한 MCP 도구를 통해 에이전트가 해당 메타데이터를 검색하고 탐색할 수 있습니다.

에이전트는 다섯 가지 중립적인 검색 도구(판결 없음, 해석 없음)를 통해 레이크에 접근합니다:

search_context(query, k?, filters?)

— 메타데이터 필터를 사용한 시맨틱 k-NN (semantic k-NN) 검색.

get_document(document_id)

— 재조립된 청크(chunks)를 포함한 전체 문서.

list_sources()

— 설정된 소스 목록.

find_related(entity, relationship_types?, k?)

— 관계 검색 (retrieve relationships): 추출된 관계가 특정 엔티티(entity)를 가리키는 항목과 해당 엔티티를 참조하는 항목을 검색하여, 매칭 방식에 따라 병합 및 주석을 달아 반환합니다.

list_entities(document_id?, entity_type?)

— 추출된 고유한 {type, name} 엔티티(예: 서비스, 데이터스토어, Jira 키 등)에 대한 중립적인 인벤토리 (inventory).

벡터 스토어 (Vector store): Amazon OpenSearch Serverless (k-NN 벡터)
컴퓨팅 (Compute): 데이터 수집(ingestion)을 위한 Lambda (SQS fan-out), 지속적인 MCP 서버를 위한 Fargate
임베딩 (Embeddings): VPC (PrivateLink) 엔드포인트를 통한 Amazon Bedrock
커넥터 (Connectors): GitHub (이슈, PR, README, 토론); Connector 인터페이스를 통해 추가 가능

전체 문서는 docs/에 있습니다:

• Architecture — 단일 스택 CDK 설계 및 파이프라인.
• Concepts — 컨텍스트 레이크 (Context Lake), 시맨틱 인덱싱 (Semantic Indexing), 중립성 원칙 (Neutrality Principle), MCP.
• Getting Started — 스택을 사용자의 AWS 계정에 배포하는 방법.
• Contributing — SourceType / 커넥터 또는 인터셉터(interceptor) 추가 방법.

src/aquifer/ # Python 패키지: core, connectors, adapters, ingestion Lambdas, MCP server
infrastructure/ # AWS CDK (Python) — 단일 배포 가능 스택
scripts/ # 개발 도구 (예: 시맨틱 인덱싱 평가 하네스)
...

추출 품질은 aquifer/semantic/prompts.py에 있는 모듈형 프롬프트(prompts)에 의해 제어됩니다. 프롬프트를 튜닝하려면 tests/eval_data/에 있는 골든 아티팩트(golden artifacts)에 대해 평가 하네스(eval harness)를 실행하세요. 실행 시 선택된 프롬프트, 생성된 중립적 메타데이터 JSON, 그리고 예상되는 목적 필드(엔티티 이름, 관계 대상)에 대한 재현율(recall)이 출력됩니다:

python scripts/eval_semantic_index.py # 모든 예시 (사용자의 Bedrock 호출)
python scripts/eval_semantic_index.py --name jira --verbose

점수 산정은 의도적으로 중립적입니다. 이는 어떠한 판단이 아니라, 올바른 *사실(facts)*을 추출했는지를 측정합니다. 더 많은 *.json

examples를 tests/eval_data/에 추가하여 커버리지를 넓혀가세요.

코어(Core)는 의도적으로 가볍게 설계되었습니다. 횡단 관심사(Cross-cutting concerns, 예: SSO, RBAC, 감사 로그)는 이 베이스라인에 포함되지 않습니다. 대신, 코어는 통과(pass-through) 방식의 no-op 구현을 가진 Interceptor 접점(before/after_ingest, before/after_query, authorize)을 노출합니다. 엔터프라이즈 기능은 인터셉터를 등록하는 별도의 패키지로 제공되며, 코어는 엔터프라이즈 코드를 절대 임포트(import)하지 않습니다.

전체 Context Lake를 단일 CDK 스택으로서 귀하의 AWS 계정에 배포하십시오. 기본적인 실행 경로는 아래와 같습니다. 구성 키(configuration keys), 인제스션(ingestion) 상세 정보 및 문제 해결에 대해서는 'Getting Started'를 참조하십시오.

사전 요구 사항

• Docker 실행 중 — CDK는 배포 시점에 Lambda 코드를 번들링하고 MCP 이미지를 로컬에서 빌드합니다.
• AWS CLI v2 — 자격 증명이 설정되어 있어야 합니다 (aws configure).
• Amazon Bedrock 모델 액세스 — 대상 리전에서 임베딩 모델(Titan Text Embeddings v2) 및 추론(Claude) 모델에 대한 액세스가 활성화되어 있어야 합니다.

1. 설치 및 부트스트랩(Bootstrap)

pip install -e ".[dev,cdk]" # 패키지 + 도구 + CDK 라이브러리
npm install -g aws-cdk # CDK Toolkit CLI
export CDK_DEFAULT_ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
...

2. 스택 배포

cdk deploy -c repos='["your-org/your-repo"]'

완료되면 CloudFormation이 McpEndpoint(내부 MCP API) 및 GitHubTokenSecretArn(다음에 채워 넣을 비밀값)을 포함한 스택 출력(stack outputs)을 출력합니다.

3. GitHub 토큰 주입

대상 리포지토리에 대한 읽기 권한이 있는 세분화된 PAT(fine-grained PAT)를 생성된 시크릿(secret)에 저장하십시오:

aws secretsmanager put-secret-value \
--secret-id <GitHubTokenSecretArn> \
--secret-string 'ghp_xxxxxxxxxxxxxxxxxxxx'

디스커버리(Discovery)는 스케줄에 따라 실행됩니다(기본값은 15분마다). 이후 인제스션(ingestion), 시맨틱 인덱싱(semantic indexing) 및 임베딩(embedding)이 자동으로 진행됩니다.

설계 방식에 따라, Aquifer는 격리된 VPC(isolated VPC)에 배포되며 공개 엔드포인트(public endpoints)를 노출하지 않습니다 — 인터넷에서 접근 가능한 것은 아무것도 없으며, 어떤 데이터도 귀하의 네트워크를 벗어나지 않습니다. MCP API는 내부(internal) 로드 밸런서(McpEndpoint)에서 서비스되므로, localhost에서 호출하는 것은 작동하지 않습니다.

네트워크 경계 내부에서 MCP API에 접근하십시오. 예를 들어, VPC 내의 EC2 bastion 또는 Cloud9 환경, 또는 Client VPN이나 VPC peering을 통한 귀하의 로컬 머신에서 접근할 수 있습니다. MCP 기능을 갖춘 에이전트를 HTTP/SSE를 통해 McpEndpoint로 지정하면 search_context, find_related, list_entities 및 기타 도구들을 호출할 수 있습니다.

Business Source License 1.1 (BSL 1.1) — LICENSE 파일을 참조하십시오. 변경 날짜(Change Date)에 Apache 2.0으로 전환됩니다.