Metadata-Version: 2.4
Name: yiqiao
Version: 0.2.2
Summary: YiQiao 自托管 AI 记忆核心 / Self-hosted AI memory core
Project-URL: Homepage, https://github.com/daizhongming/YiQiao
Project-URL: Repository, https://github.com/daizhongming/YiQiao.git
Project-URL: Issues, https://github.com/daizhongming/YiQiao/issues
Project-URL: Documentation, https://github.com/daizhongming/YiQiao/tree/main/docs/yiqiao
Author: YiQiao Contributors
Maintainer: YiQiao Maintainers
License-Expression: Apache-2.0
License-File: LICENSE
License-File: MODIFICATIONS.md
License-File: NOTICE
License-File: THIRD_PARTY_NOTICES.md
Keywords: agents,ai,memory,self-hosted,yiqiao
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: <4.0,>=3.10
Requires-Dist: httpx>=0.28.0
Requires-Dist: openai>=1.90.0
Requires-Dist: posthog>=7.14.0
Requires-Dist: protobuf<7.0.0,>=5.29.6
Requires-Dist: pydantic>=2.7.3
Requires-Dist: pytz>=2024.1
Requires-Dist: qdrant-client>=1.12.0
Requires-Dist: sqlalchemy>=2.0.31
Provides-Extra: dev
Requires-Dist: isort>=5.13.2; extra == 'dev'
Requires-Dist: pytest>=8.2.2; extra == 'dev'
Requires-Dist: ruff>=0.6.5; extra == 'dev'
Provides-Extra: extras
Requires-Dist: boto3>=1.34.0; extra == 'extras'
Requires-Dist: elasticsearch<9.0.0,>=8.0.0; extra == 'extras'
Requires-Dist: fastembed>=0.3.1; extra == 'extras'
Requires-Dist: langchain-community<1.0.0,>=0.4.2; extra == 'extras'
Requires-Dist: langchain-core<2.0.0,>=1.2.22; extra == 'extras'
Requires-Dist: langchain<2.0.0,>=1.3.9; extra == 'extras'
Requires-Dist: opensearch-py>=2.0.0; extra == 'extras'
Requires-Dist: scipy<1.16.0,>=1.11.0; extra == 'extras'
Requires-Dist: sentence-transformers>=5.0.0; extra == 'extras'
Provides-Extra: llms
Requires-Dist: anthropic<1.0.0,>=0.39.0; extra == 'llms'
Requires-Dist: google-cloud-aiplatform<2.0.0,>=1.133.0; extra == 'llms'
Requires-Dist: google-genai>=1.0.0; extra == 'llms'
Requires-Dist: google-generativeai>=0.3.0; extra == 'llms'
Requires-Dist: groq>=0.3.0; extra == 'llms'
Requires-Dist: litellm<1.92.0,>=1.91.3; extra == 'llms'
Requires-Dist: ollama>=0.3.0; extra == 'llms'
Requires-Dist: openai>=1.90.0; extra == 'llms'
Requires-Dist: together>=0.2.10; extra == 'llms'
Provides-Extra: nlp
Requires-Dist: spacy>=3.7.0; extra == 'nlp'
Provides-Extra: test
Requires-Dist: langchain-core<2.0.0,>=1.2.22; extra == 'test'
Requires-Dist: pytest-asyncio>=0.23.7; extra == 'test'
Requires-Dist: pytest-mock>=3.14.0; extra == 'test'
Requires-Dist: pytest>=8.2.2; extra == 'test'
Requires-Dist: python-dotenv<2.0.0,>=1.0.0; extra == 'test'
Requires-Dist: tiktoken==0.12.0; extra == 'test'
Provides-Extra: vector-stores
Requires-Dist: azure-identity>=1.24.0; extra == 'vector-stores'
Requires-Dist: azure-search-documents>=11.4.0b8; extra == 'vector-stores'
Requires-Dist: cassandra-driver>=3.29.0; extra == 'vector-stores'
Requires-Dist: chromadb==0.5.4; extra == 'vector-stores'
Requires-Dist: databricks-sdk>=0.63.0; extra == 'vector-stores'
Requires-Dist: dbutils>=3.0.3; extra == 'vector-stores'
Requires-Dist: elasticsearch<9.0.0,>=8.0.0; extra == 'vector-stores'
Requires-Dist: faiss-cpu>=1.7.4; extra == 'vector-stores'
Requires-Dist: google-cloud-aiplatform<2.0.0,>=1.133.0; extra == 'vector-stores'
Requires-Dist: langchain-aws<2.0.0,>=1.0.0; extra == 'vector-stores'
Requires-Dist: pinecone-text>=0.10.0; extra == 'vector-stores'
Requires-Dist: pinecone<=7.3.0; extra == 'vector-stores'
Requires-Dist: psycopg-pool<4.0.0,>=3.2.6; extra == 'vector-stores'
Requires-Dist: psycopg[binary]>=3.2.8; extra == 'vector-stores'
Requires-Dist: pyasyncore<2.0.0,>=1.0.5; (python_version >= '3.12') and extra == 'vector-stores'
Requires-Dist: pymilvus<2.6.0,>=2.4.0; extra == 'vector-stores'
Requires-Dist: pymochow>=2.2.9; extra == 'vector-stores'
Requires-Dist: pymongo>=4.13.2; extra == 'vector-stores'
Requires-Dist: pymysql>=1.1.0; extra == 'vector-stores'
Requires-Dist: redis<6.0.0,>=5.0.0; extra == 'vector-stores'
Requires-Dist: redisvl<1.0.0,>=0.1.0; extra == 'vector-stores'
Requires-Dist: turbopuffer<3.0.0,>=2.0.0; extra == 'vector-stores'
Requires-Dist: upstash-vector>=0.6.0; extra == 'vector-stores'
Requires-Dist: valkey>=6.0.0; extra == 'vector-stores'
Requires-Dist: vecs>=0.4.0; extra == 'vector-stores'
Requires-Dist: weaviate-client<5.0.0,>=4.15.4; extra == 'vector-stores'
Description-Content-Type: text/markdown

# YiQiao
> **Modification notice:** This file was modified in 2026 by YiQiao contributors. See NOTICE.

[简体中文](README.zh-CN.md) | **English**

YiQiao is a self-hosted memory service for AI assistants and agents. It combines
an authenticated REST API, an operations dashboard, semantic and graph-backed
memory, chat-history import, export, usage controls, and webhooks in one Docker
Compose deployment. Integrations authenticate with project-scoped API keys.

## Quick Start

Requirements: Git, Docker Desktop or Docker Engine with Docker Compose v2, and
outbound HTTPS access for pulling images and calling the model provider you
choose during setup. The Linux and macOS API examples require curl 7.76 or
newer.

Linux and macOS:

```bash
git clone https://github.com/daizhongming/YiQiao.git
cd YiQiao
./scripts/init.sh
cd server
docker compose up -d
```

Windows PowerShell:

```powershell
git clone https://github.com/daizhongming/YiQiao.git
Set-Location YiQiao
powershell -ExecutionPolicy Bypass -File .\scripts\init.ps1
Set-Location server
docker compose up -d
```

Open <http://localhost:3000>. The first-run wizard creates the administrator,
configures the model and embedding providers, issues the first project API key,
and performs a memory write. The initialization script creates `server/.env`
and strong local secrets without overwriting an existing file.

| Service | Default address | Override |
| --- | --- | --- |
| Dashboard | <http://localhost:3000> | `DASHBOARD_PORT` |
| REST API | <http://localhost:8888> | `API_PORT` |
| OpenAPI | <http://localhost:8888/docs> | follows `API_PORT` |
| Health | <http://localhost:8888/api/health> | follows `API_PORT` |

Confirm that the stack is ready on Linux or macOS:

```bash
docker compose ps
curl --fail http://localhost:8888/api/health
```

On Windows PowerShell:

```powershell
docker compose ps
Invoke-RestMethod -Uri "http://localhost:8888/api/health"
```

The default Compose file pulls release images from GitHub Container Registry.
To build the API and dashboard from the checked-out source instead, run from
the repository root on Linux or macOS:

```bash
cd server
docker compose -f docker-compose.yaml -f docker-compose.build.yaml up -d --build
```

On Windows PowerShell:

```powershell
Set-Location server
docker compose -f docker-compose.yaml -f docker-compose.build.yaml up -d --build
```

<a id="verify-memory-add-and-search"></a>

## Verify Memory Add and Search

Complete the browser setup first and retain the API key shown once by the
wizard. The default project identifier is `default-project`.

Linux and macOS:

```bash
export YIQIAO_API_URL=http://localhost:8888
export YIQIAO_API_KEY='<your-api-key>'
export YIQIAO_PROJECT_ID=default-project

curl --fail-with-body -X POST "$YIQIAO_API_URL/memories" \
  -H "X-API-Key: $YIQIAO_API_KEY" \
  -H "X-Project-ID: $YIQIAO_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"I prefer concise answers."}],"user_id":"quickstart-user"}'

curl --fail-with-body -X POST "$YIQIAO_API_URL/search" \
  -H "X-API-Key: $YIQIAO_API_KEY" \
  -H "X-Project-ID: $YIQIAO_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{"query":"How should answers be written?","filters":{"user_id":"quickstart-user"}}'
```

Windows PowerShell:

```powershell
$apiUrl = "http://localhost:8888"
$headers = @{
  "X-API-Key" = "<your-api-key>"
  "X-Project-ID" = "default-project"
}
$addBody = @{
  messages = @(@{ role = "user"; content = "I prefer concise answers." })
  user_id = "quickstart-user"
} | ConvertTo-Json -Depth 4
Invoke-RestMethod -Method Post -Uri "$apiUrl/memories" -Headers $headers -ContentType "application/json" -Body $addBody

$searchBody = @{
  query = "How should answers be written?"
  filters = @{ user_id = "quickstart-user" }
} | ConvertTo-Json -Depth 4
Invoke-RestMethod -Method Post -Uri "$apiUrl/search" -Headers $headers -ContentType "application/json" -Body $searchBody
```

## Python Entry Point

Install the published Python package:

```bash
python -m pip install yiqiao
```

YiQiao provides synchronous and asynchronous Python entry points:

```python
from yiqiao import Memory, AsyncMemory
```

Local state is stored in `~/.yiqiao` by default and can be moved with
`YIQIAO_DIR`.

For a standalone service integration, use the REST API and project API keys
shown above.

## What YiQiao Provides

- Project-scoped memory add, search, update, delete, history, and feedback APIs.
- A dashboard for memories, entities, graph exploration, requests, API keys,
  configuration, usage limits, exports, imports, and webhooks.
- PostgreSQL with pgvector for application and vector data, plus optional Neo4j
  graph relationships.
- Browser-based provider configuration for bundled LLM and embedding adapters,
  including custom OpenAI-compatible base URLs.
- Authentication enabled by default, administrator onboarding, project API keys,
  role-aware workspace access, and request logging.
- Chat-history import with progress, retry, cancellation, and storage quotas.

Typical uses include persistent assistant preferences, support context, research
memory, coding-agent context, and private knowledge workflows where the operator
needs to own the storage and model-provider relationship.

## Architecture

```text
Browser / API clients
        |
        +--> Dashboard :3000
        |         |
        +---------+--> YiQiao API :8888 --> selected model providers
                             |  \
                             |   +--> Neo4j Community (graph)
                             +------> PostgreSQL + pgvector (auth, settings,
                                      requests, vectors, memory metadata)
```

Dashboard browser requests reach the API through `NEXT_PUBLIC_API_URL`; its
server-side requests use `API_INTERNAL_URL` over the internal Compose network.
PostgreSQL and Neo4j are internal-only by default. Database and graph state is
stored in named Docker volumes, memory-history SQLite and import workspace state
under `server/history/`, and deployment configuration and generated secrets in
`server/.env`. Export job records and results are stored in PostgreSQL; files
downloaded from the dashboard are retained by the client. Provider calls leave
the deployment over HTTPS when a remote provider is configured.

## Configuration

The recommended configuration path is the first-run wizard at
<http://localhost:3000/setup>. It discovers the providers bundled into the API
image and lets an administrator set provider, model, base URL, and API key.
Provider credentials are not required for containers to start, but memory
extraction and semantic search require a working LLM and embedder configuration.

Deployment settings live in `server/.env`. The generated defaults keep
authentication enabled, telemetry disabled, database services off host ports,
and secrets out of version control. Do not expose the API or dashboard directly
to the internet; terminate TLS at a trusted reverse proxy and restrict access to
the intended network.

See [Operations](docs/yiqiao/OPERATIONS.md) for ports, persistence, backup,
upgrade, source builds, and removal.

## Documentation

- [Operations](docs/yiqiao/OPERATIONS.md)
- [Migration](docs/yiqiao/MIGRATION.md)
- [Troubleshooting](docs/yiqiao/TROUBLESHOOTING.md)
- [Licensing and provenance](docs/yiqiao/LEGAL.md)
- [Security policy](SECURITY.md)
- [Contributing](CONTRIBUTING.md)
- [Third-party notices](THIRD_PARTY_NOTICES.md)
- [Modification notices](MODIFICATIONS.md)

## Known Limits

- The default deployment is a single-host Compose stack, not a high-availability
  cluster.
- Neo4j Community does not provide the enterprise online-backup and clustering
  features. Plan a maintenance window for graph-volume snapshots.
- Provider behavior, privacy, rate limits, and data residency remain the
  operator's responsibility.
- Version `0.1.x` is an initial open-source product line; deployment and API
  compatibility should be reviewed before each upgrade.

Current roadmap priorities are reproducible image provenance and SBOMs,
documented external database deployments, stronger backup automation, and a
versioned compatibility policy. Roadmap items are directional and have no
committed delivery date.

## License and Third-Party Notices

YiQiao is an independently maintained and released open-source product under
the Apache License 2.0. See [LICENSE](LICENSE), [NOTICE](NOTICE),
[Third-Party Notices](THIRD_PARTY_NOTICES.md), and
[Modification Notices](MODIFICATIONS.md) for licensing, attribution, and the
record of changes.
