- SymbolicAI는 고전적 Python 프로그래밍과 LLM의 미분 가능하고 프로그래밍 가능한 성격을 결합하는 신경-기호 프레임워크로, Python 안에서 자연스럽게 쓰는 것을 목표로 함
- 핵심 개념은
Symbol 객체 기반의 프리미티브와 LLM 결과를 검증·수정하는 계약(contracts) 이며, 기본 동작은 안전성과 속도를 위해 구문적 모드로 시작함
Symbol은 구문적 모드에서는 일반 Python 값처럼 동작하고, 의미적 모드에서는 문맥과 의미를 다루며 semantic=True, .sem, .map() 같은 의미 함수 호출로 전환 가능함- 계약 시스템은 Design by Contract 원칙을 LLM 워크플로에 적용해 입력 검증, 상태 변경, LLM 생성, 출력 검증, 실패 시 대체 응답까지 하나의 데코레이터 기반 흐름으로 다룸
- 설치는
pip install symbolicai로 시작하며, 실제 사용에는 symconfig와 symai.config.json 설정이 필요하고, 신경-기호 엔진은 symai 패키지 사용에 필수임
SymbolicAI가 지향하는 모델
- SymbolicAI는 신경-기호(neuro-symbolic) 프레임워크로, 일반 Python 코드와 LLM 기반 의미 처리를 함께 다룸
- 모듈형 설계를 통해 필요에 맞게 확장·커스터마이즈할 수 있음
- 자체 엔진 작성, 로컬 엔진 호스팅, 웹 검색, 이미지 생성 같은 도구 연동을 지원함
- 프로젝트 이름은 Allen Newell과 Herbert Simon의 기초 작업에 대한 크레딧을 의도함
Symbol 프리미티브
- SymbolicAI의 중심에는
Symbol 객체가 있으며, 작은 조합 가능한 연산을 Python 네이티브 문법처럼 사용할 수 있음
Symbol은 두 가지 동작 방식을 가짐
- Syntactic: 전달한 문자열, 리스트, 정수 같은 일반 Python 값처럼 동작함
- Semantic: 신경-기호 엔진과 연결되어 의미와 문맥을 다룸
- 기본값은 구문적 모드임
==, ~, & 같은 Python 연산자가 symai에서 오버로드되어 있음- 모든 비교나 비트시프트에서 곧바로 엔진을 호출하면 느려지고 예상치 못한 부작용이 생길 수 있음
- 필요한 지점에서만 의미적 동작을 켜는 방식으로 안전성과 속도를 유지함
의미적 모드로 전환하는 방법
- 생성 시점에
semantic=True를 지정하면 처음부터 의미적 Symbol로 동작함
- 예시에서
Symbol("Cats are adorable", semantic=True)는 "feline" in S를 True로 처리함
- 필요할 때
.sem 프로젝션을 사용해 의미적 동작으로 전환할 수 있으며, .syn으로 다시 구문적 동작으로 돌아갈 수 있음
- 같은
"Cats are adorable" 값도 S.sem에서는 "feline" in S.sem이 True이고, 기본 S에서는 False임
.map() 같은 점 표기법 연산이나 다른 의미 함수 호출은 자동으로 Symbol을 의미적 모드로 전환함
- 예시에서 과일 목록에
convert all fruits to vegetables를 적용하면 과일만 채소로 바꾸고 cat, dog는 유지함
.sem과 .syn 프로젝션은 같은 기본 객체에 다른 동작 계층을 씌우는 방식이어서, 하나의 Symbol 위에서 구문적·의미적 연산을 이어 붙일 수 있음
제공되는 연산 예시
- SymbolicAI는 다양한 프리미티브를 지원하며, 문서는 primitives에 있음
==는 구문적 모드에서는 리터럴 일치를 검사하고, 의미적 모드에서는 "Hi"와 "Hello" 같은 퍼지·개념적 동등성을 다룸+는 구문적 모드에서는 숫자·문자열·리스트 덧셈이고, 의미적 모드에서는 의미 있는 조합, 혼합, 개념 병합을 수행함&는 구문적 모드에서는 비트·논리 AND이고, 의미적 모드에서는 논리 결합, 추론, 문맥 병합을 다룸- 의미적 전용 기능에는
.choice(cases, default), .foreach(condition, apply), .cluster(**clustering_kwargs?), .similarity(other, metric?, normalize?) 등이 있음
.cluster()는 데이터를 의미적으로 그룹화하며 sklearn의 DBSCAN을 사용함.similarity()는 임베딩 간 유사도를 계산함
계약으로 LLM 출력을 다루는 방식
- SymbolicAI는 LLM이 환각할 수 있지만 코드는 그럴 수 없다는 문제의식에서 Design by Contract 원칙을 LLM 세계에 적용함
- 계약은 사후 테스트만 의존하지 않고, 데이터 모델과 검증 제약을 데코레이터에 묶어 설계 단계에서 올바름을 다룸
- 예시 코드의 계약 데코레이터는 다음 옵션을 사용함
pre_remedy=True: 잘못된 입력을 자동 수정 시도함post_remedy=True: 잘못된 LLM 출력을 자동 수정 시도함accumulate_errors=True: 재시도마다 오류 이력을 전달함verbose=True: 터미널에 진행 상황을 표시함remedy_retry_params: tries=3, delay=0.4, max_delay=4.0, jitter=0.15, backoff=1.8, graceful=False를 사용함
- 계약이 적용된
Expression 클래스의 고수준 흐름은 다음과 같음
prompt: LLM이 해야 할 일을 정의하는 정적 설명이며 필수임pre: 입력을 검사하며 선택 사항임act: 상태를 변경하며 선택 사항임- LLM: SymbolicAI 엔진이 기대 답변을 생성함
post: 답변이 의미 규칙을 만족하는지 확인하며 선택 사항임forward: 필수이며, 계약 성공 시 타입 검증된 LLM 객체를 반환하고 실패 시 graceful fallback 답변을 반환함
- 계약 문서는 DeepWiki의 contract validation system과 features/contracts에 있음
설치와 선택 기능
pip install symbolicai
- 저장소를 클론하고 uv
>= 0.9.17로 Python 가상환경을 구성할 수도 있음
git clone git@github.com:ExtensityAI/symbolicai.git
cd symbolicai
uv sync --python x.xx
source ./.venv/bin/activate
- SymbolicAI는 텍스트, 음성, 이미지를 처리하기 위해 여러 엔진을 사용하며, 웹 정보 검색을 위한 검색 엔진 접근도 포함함
- 선택 의존성은 기능별 extra로 설치할 수 있음
bitsandbytes, hf, lean, llama_cpp, ocr, qdrant, scrape, search, serpapi, services, solver, whisper, wolframalpha
- 모든 선택 의존성은 한 번에 설치 가능함
pip install "symbolicai[all]"
uv sync --frozen은 제공된 lock 파일에 고정된 의존성을 설치함- 일부 선택 의존성은 추가 설치 단계가 필요할 수 있고, 일부는 현재 실험적으로만 지원되어 예상대로 동작하지 않을 수 있음
설정 관리와 필수 엔진
- SymbolicAI는 우선순위 기반 설정 관리 시스템을 사용함
- 설정은 세 위치에서 우선순위 순서로 로드됨
- 현재 작업 디렉터리의 디버그 모드: 가장 높은 우선순위이며
symai.config.json에만 적용됨
- Python 환경의 환경별 설정:
{python_env}/.symai/에 위치하며 프로젝트별 설정에 적합함
- 홈 디렉터리의 전역 설정:
~/.symai/에 위치하며 기본 fallback 역할을 함
- 관리 대상 설정 파일은 세 가지임
symai.config.json: SymbolicAI 메인 설정symsh.config.json: 셸 설정symserver.config.json: 서버 설정
symconfig는 설정 위치, 활성 설정 경로, 민감 정보가 잘린 현재 설정을 보여주며, 초기 패키지 캐싱과 설정 파일 초기화를 시작함symai 패키지를 사용하려면 신경-기호 엔진이 필수임
- 프로젝트 경로의
symai.config.json에 엔진 속성을 지정하면 환경 변수를 대체함
- 예시 설정에는
NEUROSYMBOLIC_ENGINE_MODEL 값으로 claude-sonnet-4-6, 임베딩 모델로 text-embedding-3-small, TTS 모델로 tts-1, OCR 모델로 mistral-ocr-latest, 인덱싱 엔진으로 qdrant 등이 포함됨
- 기본적으로 사용자 경고가 켜져 있으며, 환경 변수
SYMAI_WARNINGS=0으로 비활성화할 수 있음
테스트, 문서, 라이선스
pytest tests
pytest -m mandatory
pytest --cov=symbolicai tests
- 테스트 전에는 설정이 올바르게 구성되어 있어야 함
- 다음 단계로 SymbolicAI DeepWiki 페이지, 논문, 비디오 튜토리얼을 참고할 수 있음
- 인용 정보는
Symbolicai: A framework for logic-based approaches combining generative models and solvers라는 2024년 arXiv preprint를 가리킴
- 프로젝트 라이선스는 BSD-3-Clause License임