Metadata-Version: 2.4
Name: ioc-knowledge-memory
Version: 0.2.3
Summary: Package for IoC knowledge management
Author: Your Organization
Author-email: Outshift by Cisco <outshiftbycisco@cisco.com>
Project-URL: Homepage, https://github.com/outshift-open/ioc-knowledge-memory
Project-URL: Repository, https://github.com/outshift-open/ioc-knowledge-memory
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: agensgraph-python==1.0.2
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.27
Requires-Dist: prometheus-fastapi-instrumentator==6.1.0
Requires-Dist: email-validator==2.1.1
Requires-Dist: requests==2.31.0
Requires-Dist: psycopg2-binary==2.9.11
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: cryptography<47.0.0,>=46.0.3
Requires-Dist: sqlalchemy==2.0.23
Requires-Dist: pydantic<3.0.0,>=2.12.5
Requires-Dist: pgvector==0.4.2
Requires-Dist: urllib3>=2.6.3
Provides-Extra: dev
Requires-Dist: black==23.11.0; extra == "dev"
Requires-Dist: flake8==6.1.0; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Dynamic: author
Dynamic: license-file
Dynamic: requires-python

# ioc-knowledge-memory-svc

ioc-knowledge-memory-svc - APIs for knowledge management

## Usage Options

This service can be accessed in two ways:

1. **HTTP API** (for external clients, microservices) - Port 9003
2. **Direct Library** (for Python in-process, 10x faster) - See [knowledge_memory](src/knowledge_memory/README.md)

## Prerequisites

- Python 3.8+
- Poetry: `curl -sSL https://install.python-poetry.org | python3 -`
- Task:
  - **macOS**: `brew install go-task`
  - **Linux**: `apt install task`, `dnf install go-task`, or `snap install task --classic`
  - **Cross-platform**: `npm install -g @go-task/cli`
  - **Go users**: `go install github.com/go-task/task/v3/cmd/task@latest`
  - **Manual install**: `sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin`
  - **All-in-one setup**: `./install.sh` (installs Poetry and Task globally, and dependencies)

## Quick Start

### Deployment Options

```bash
task docker-compose-up       # Start complete stack (application + databases)
```

### Alternative Quick Start Methods

**Dev setup (installs Poetry and Task globally)**

```bash
./install.sh
task dev
```

**Manual setup (if you have Poetry/Task already)**

```bash
poetry install
task dev
```

**API Documentation:**
http://localhost:9003/docs
http://localhost:9003/openapi.json

## Development

**Using Task**

```bash
task dev              # Start development server
task test             # Run all tests
task docker-build     # Build Docker image
task docker-run       # Run Docker container
```

**Using Poetry directly**

```bash
cd src/server
poetry run python main.py
```

**Using Docker**

```bash
docker-compose up --build
```

## Version Management

This project uses **pyproject.toml as the single source of truth** for versioning.

### How to Bump Version

**Simply edit one line in [pyproject.toml](pyproject.toml):**
```toml
[project]
version = "0.1.5"  # Change this line only!
```

**All other locations automatically sync:**
- ✅ `setup.py` - reads from pyproject.toml
- ✅ `src/knowledge_memory/__init__.py` - uses `importlib.metadata`
- ✅ `.github/workflows/ci.yaml` - dynamically reads and updates for dev builds

**No manual sync needed!** The version is automatically propagated to:
- Package metadata when building
- Runtime `__version__` attribute
- CI/CD dev builds (adds `.devYYYYMMDDHHMMSS` suffix)

### Version Format

We follow [PEP 440](https://peps.python.org/pep-0440/) versioning:
- Release versions: `0.1.4`, `0.2.0`, `1.0.0`
- Dev builds (CI): `0.1.4.dev20260316120000`

## Python Library (New!)

For **in-process, high-performance access** without HTTP overhead:

```python
from knowledge_memory import upsert_knowledge_graph, query_knowledge_graph
from knowledge_memory import onboard_vector_store, upsert_vector_store

# Direct function calls - no HTTP!
response = upsert_knowledge_graph(
    mas_id="agent-1",
    wksp_id="workspace-1",
    concepts=[{"id": "c1", "name": "Python"}]
)
```

**Benefits:**
- 🚀 **10x faster** than HTTP API (no network overhead)
- 🐍 **Type-safe** Python exceptions
- 🔧 **Same features** as HTTP API
- ✅ **No regression** - HTTP API still works

**Documentation:** See [src/knowledge_memory/README.md](src/knowledge_memory/README.md)

**Quick test:**
```bash
python src/knowledge_memory/examples.py     # Run examples
pytest tests/test_knowledge_memory.py -v    # Run tests
python3 validate_knowledge_memory.py        # Validate structure
```
