SymbolicAI는 고전적인 Python 프로그래밍과 LLM의 미분 가능한(differentiable), 프로그래밍 가능한 특성을 결합한 신경-기호적(neuro-symbolic) 프레임워크로, 마치 Python에서 자연스럽게 느껴지도록 설계되었습니다.

이 프레임워크는 사용자의 야망에 방해가 되지 않도록 구축되었습니다. 모듈식 디자인 덕분에 필요에 따라 쉽게 확장하고 사용자 정의할 수 있습니다. 또한 자체 엔진을 작성하거나, 원하는 엔진을 로컬에서 호스팅하거나, 웹 검색 또는 이미지 생성과 같은 도구와 인터페이스하는 것이 매우 쉽습니다.

이 README를 간결하게 유지하기 위해 SymbolicAI를 정의하는 두 가지 핵심 개념인 **프리미티브(primitives)**와 **컨트랙트(contracts)**를 소개하겠습니다.

❗️

NOTE❗️ 이 프레임워크의 이름은 본 프로젝트에 영감을 준 Allen Newell과 Herbert Simon의 기초 연구에 경의를 표하기 위함입니다.

SymbolicAI의 핵심에는 Symbol 객체가 있습니다. 각 Symbol은 네이티브 Python처럼 느껴지는 작고 조합 가능한 연산자 세트를 가지고 있습니다.

from symai import Symbol

Symbol은 **두 가지 종류(flavours)**로 나뉩니다:

문법적(Syntactic) – 일반적인 Python 값(문자열, 리스트, 정수 등 입력한 모든 것)처럼 동작합니다.
의미론적(Semantic) – 신경-기호 엔진에 연결되어 있어 의미와 문맥을 이해합니다.

왜 문법적이 기본값인가요?
Python 연산자(==, ~, &, …)가 symai에서 오버로딩되었기 때문입니다. 만약 모든 비트 이동이나 비교에 대해 즉시 엔진을 가동한다면, 코드가 느려지고 예상치 못한 부작용이 발생할 수 있습니다. 기본값을 문법적으로 유지하면 안전하고 빠르며, 필요한 곳에서만 의미론적(semantics)으로 전환할 수 있습니다.

생성 시점(At creation time)
`S = Symbol(

또는 다른 의미론적 함수—심볼을 자동으로 의미론 모드(semantic mode)로 전환합니다: S = Symbol(['apple', 'banana', 'cherry', 'cat', 'dog']) print(S.map('convert all fruits to vegetables')) # => ['carrot', 'broccoli', 'spinach', 'cat', 'dog']

투영(projections)이 단지 다른 행동적 외피만 가진 동일한 근본 객체를 반환하기 때문에, 하나의 심볼에 대해 구문론적 및 의미론적 연산을 복잡하게 엮을 수 있습니다. 이것들을 의미 추론을 위한 빌딩 블록이라고 생각하세요. 현재 광범위한 기본 요소(primitives)를 지원합니다. 여기에서 문서를 확인해 보세요. 하지만 간단히 살펴보겠습니다:

LLM이 환각(hallucinate)을 일으킨다고들 하지만, 여러분의 코드는 그렇게 할 여유가 없습니다. 이것이 SymbolicAI가 계약 기반 설계(Design by Contract) 원칙을 LLM 세계에 도입하는 이유입니다. 단순히 사후 테스트(post-hoc testing)에만 의존하는 대신, 계약은 설계 자체에 정확성을 구축하도록 돕습니다. 모든 것이 정의된 데이터 모델과 검증 제약 조건에서 작동할 데코레이터 안에 패키징됩니다:

from symai import Expression
from symai.strategy import contract
from symai.models import LLMDataModel # Pydantic의 BaseModel과 호환됨
...

이 README 파일을 긴 Python 코드 스니펫으로 부풀리고 싶지 않으므로, 계약에 대한 자세한 내용은 여기와 여기에서 알아보세요.

SymbolicAI를 시작하려면 pip을 사용하여 설치할 수 있습니다:

pip install symbolicai

또는 저장소를 클론하고 uv (>= 0.9.17)를 사용하여 Python 가상 환경을 설정할 수 있습니다:

git clone [email protected]:ExtensityAI/symbolicai.git
cd symbolicai
uv sync --python x.xx
...

symconfig를 실행하면 이제 이 Python 환경을 사용하게 됩니다.

SymbolicAI는 텍스트, 음성 및 이미지를 처리하기 위해 여러 엔진을 사용합니다. 또한 웹에서 정보를 검색할 수 있는 검색 엔진 액세스도 포함하고 있습니다. 이 모든 것을 사용하려면 다음 종속성(dependencies)도 설치하고 해당 엔진에 API 키를 할당해야 합니다. 예:

pip install "symbolicai[cluster]"
pip install "symbolicai[hf]"
pip install "symbolicai[lean]"
...

또는 모든 선택적 종속성을 한 번에 설치합니다:

pip install "symbolicai[all]"

제공된 잠금 파일(lock file)에 고정된 대로 정확하게 종속성을 설치하려면:

uv sync --frozen

uv를 통해 선택적 추가 기능(optional extras)을 설치하려면:

uv sync --extra all # 모든 선택적 추가 기능
uv sync --extra scrape # 스크랩만```

❗️

참고 사항❗️이러한 일부 선택적 종속성은 추가적인 설치 단계가 필요할 수 있다는 점에 유의하십시오. 또한, 일부는 현재 실험적으로 지원되는 것이므로 예상대로 작동하지 않을 수 있습니다. 특정 기능이 매우 중요하다면, 프로젝트에 기여하거나 저희에게 문의하는 것을 고려해 주십시오.

SymbolicAI는 이제 우선순위 기반 로딩을 갖춘 구성 관리 시스템을 제공합니다. 이 구성 시스템은 다음 세 가지 위치에서 설정값을 순서대로 찾습니다:

- **디버그 모드**(현재 작업 디렉토리) - 최고 우선순위
  - `symai.config.json`에만 적용됨
  - 개발 및 테스트에 유용함

- **환경별 설정**(Python 환경) - 두 번째 우선순위
  - `{python_env}/.symai/`에 위치함
  - 프로젝트별 설정에 이상적임

- **전역 설정**(홈 디렉토리) - 최저 우선순위
  - `~/.symai/`에 위치함
  - 모든 설정의 기본 폴백(fallback)

이 시스템은 두 가지 주요 구성 파일을 관리합니다:

`symai.config.json`
: 메인 SymbolicAI 구성
`symserver.config.json`
: 서버 구성

`symai`를 사용하기 전에, 아래 명령어를 사용하여 현재의 구성 설정을 확인하는 것을 권장합니다. 이 명령어는 초기 패키지 캐싱을 시작하고 `symbolicai` 구성을 초기화할 것입니다.

smconfig

UserWarning: No configuration file found for the environment. A new configuration file has been created at <full-path>/.symai/symai.config.json. Please configure your environment.

그런 다음 `symai.config.json` 파일을 편집해야 합니다. `symai` 패키지를 사용하려면 신경심볼 추론(neurosymbolic engine)이 **필수**입니다. 신경심볼 엔진을 사용하는 방법에 대해 자세히 여기에서 읽어보세요.

이 명령어는 다음을 보여줄 것입니다:

- 모든 구성 위치
- 활성 구성 경로
- 현재 설정값 (민감한 데이터는 잘림)

my_project/ # 디버그 모드 (최고 우선순위)
└── symai.config.json # 디버그 모드에서는 이 파일만 확인됨
{python_env}/.symai/ # 환경 설정 (두 번째 우선순위)
...

여러 위치에 구성 파일이 존재하는 경우, 시스템은 최고 우선순위 버전을 사용합니다. 환경별 구성이 누락되거나 유효하지 않은 경우, 시스템은 자동으로 홈 디렉토리의 전역 구성으로 폴백됩니다.

- 전역 구성(`~/.symai/`) 사용

) 기본 설정에 대해서는 환경별 설정을 프로젝트별 설정에 사용하세요.
- 개발 및 테스트를 위해 디버그 모드(현재 디렉토리)를 사용하세요.
- 현재 구성 설정을 확인하려면 `symconfig`를 실행하세요.

프로젝트 경로의 `symai.config.json` 파일에 엔진 속성을 지정할 수 있습니다. 이렇게 하면 환경 변수를 대체합니다.
예시: 모든 엔진이 활성화된 구성 파일:

{
"NEUROSYMBOLIC_ENGINE_API_KEY": "<ANTHROPIC_API_KEY>",
"NEUROSYMBOLIC_ENGINE_MODEL": "anthropic:claude-sonnet-4-6",
...
}

이 단계들을 완료하면 프로젝트에서 SymbolicAI를 사용하기 준비가 된 것입니다.

❗️

참고 사항❗️모델 이름은 제공업체 접두사(`openai:gpt-5.4`, `anthropic:claude-sonnet-4-6`, `gemini:gemini-3.5-flash`)를 가집니다. 이 접두사는 제공업체를 선택합니다. 모든 엔진은 공유된 `httpx` 전송 계층을 통해 순수 REST로 통신하므로, 별도의 제공업체 SDK가 필요하지 않습니다.

❗️

참고 사항❗️SymbolicAI는 기본적으로 `symai` 로거의 표준 `logging` 모듈을 통해 로그를 기록하며, 기본 설정에서는 로그가 출력되지 않습니다. 로그를 보려면 애플리케이션에서 로깅을 구성해야 합니다. 예를 들어, `logging.basicConfig(level=logging.INFO)` 또는 범위 지정 방식으로 `logging.getLogger(

이 프로젝트는 BSD-3-Clause License 하에 라이선스가 부여됩니다.

본 프로젝트가 마음에 드셨다면 별점 ⭐️을 남겨주시고 친구 및 동료들과 공유해 주세요. 이 프로젝트의 지속적인 개발을 더욱 지원하기 위해 기부하는 것을 고려해 주시면 감사하겠습니다. 감사합니다!

또한, 저희는 본 프로젝트를 성장시키고 지원할 기여자 또는 투자자를 찾고 있습니다. 관심이 있으시다면 연락 주시기 바랍니다.

본 프로젝트에 대한 질문은 이메일, 웹사이트 또는 Discord에서 언제든지 문의해 주세요: