Metadata-Version: 2.4
Name: alphasix-axiom
Version: 1.1.5
Summary: Axiom - the AI engine library behind QuantumDrive
Author: Chris Steel
Author-email: chris.steel@alphsix.com
License: LicenseRef-AlphSix-Proprietary
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11,<3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: agentfoundry<1.6,>=1.5.55
Requires-Dist: langchain
Requires-Dist: langchain-core
Requires-Dist: langchain-community
Requires-Dist: langchain-milvus
Requires-Dist: langgraph
Requires-Dist: langgraph-prebuilt
Requires-Dist: langgraph-checkpoint<5,>=4.1
Requires-Dist: langgraph-checkpoint-sqlite==3.0.3
Requires-Dist: langgraph-checkpoint-postgres==3.0.4
Requires-Dist: pymilvus
Requires-Dist: openai
Requires-Dist: langchain-openai<2,>=1.2.1
Requires-Dist: Jinja2~=3.1.5
Requires-Dist: msal==1.34.0
Requires-Dist: azure-identity==1.25.2
Requires-Dist: python-dotenv==1.2.1
Requires-Dist: toml==0.10.2
Requires-Dist: boto3==1.42.29
Requires-Dist: botocore==1.42.29
Requires-Dist: psycopg2-binary==2.9.11
Requires-Dist: prometheus-client==0.26.0
Requires-Dist: sqlalchemy==2.0.45
Requires-Dist: duckdb<2.0,>=1.0
Requires-Dist: pyarrow<26,>=15
Requires-Dist: neo4j<7.0,>=6.2
Requires-Dist: cryptography<47,>=46.0.5
Requires-Dist: packaging==26.2
Requires-Dist: pqcrypto==0.4.0
Requires-Dist: pycryptodome==3.23.0
Requires-Dist: pydantic<3,>=2.10.6
Requires-Dist: PyMuPDF==1.27.2.2
Requires-Dist: pypdf<7,>=6.12.2
Requires-Dist: python-docx==1.2.0
Requires-Dist: requests>=2.31.0
Requires-Dist: urllib3==2.6.3
Requires-Dist: PyYAML==6.0.2
Requires-Dist: torch~=2.6.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Axiom

The AI engine library behind QuantumDrive, built on AgentFoundry.

## Overview

Axiom is an AlphaSix IP library that provides:
- **Q Assistant**: Conversational AI with memory and tool access
- **Microsoft 365 Integration**: SSO and Graph API access
- **Vector Storage**: Semantic search via AgentFoundry's `VectorStoreFactory`, typically backed by Milvus
- **Knowledge Graph**: Configurable AgentFoundry KGraph backend, using local DuckDB or hosted Postgres/Neo4j
- **Delivery Planning**: Dependency-aware, multi-repo wave planning and execution primitives
- **AgentFoundry Integration**: Leverages Syntheticore's AgentFoundry library

Axiom is a **library**: it has no web server, no UI, and no application-specific secrets. A host application (QuantumDrive is the first one) imports `core.*`, supplies configuration, and owns everything user-facing.

## Quick Start

### Standalone Usage

1. **Install dependencies**:
   ```bash
   pip install -r requirements.txt
   ```

   For packaging, license generation, and PQC-related tests, install the build extras:
   ```bash
   make install-build-deps
   ```

2. **Create configuration** (choose one):

   **Option A: Project root (for development)**:
   ```bash
   cp core/config/resources/default_axiom.toml axiom.toml
   ```

   **Option B: User config directory (for production)**:
   ```bash
   mkdir -p ~/.config/axiom
   cp core/config/resources/default_axiom.toml ~/.config/axiom/axiom.toml
   ```

3. **Set environment variables**:
   ```bash
   export AF_OPENAI_API_KEY="sk-..."
   export QD_MS_TENANT_ID="..."
   export QD_MS_CLIENT_ID="..."
   export QD_MS_CLIENT_SECRET="..."
   ```

4. **Generate a development license**:
   ```bash
   make generate-keys                      # one-time: vendor signing keypair
   make generate-license DAYS=365 UNBOUND=1
   ```

5. **Verify the install**:
   ```bash
   python -c "from core.config import QDConfig; print('Axiom ready:', QDConfig().agentfoundry.llm.provider)"
   ```
   This imports `core`, which is where license enforcement runs, and resolves
   the config - so it fails loudly if either the licence or the TOML is wrong.

### Library Usage (from a host application)

```python
from core.config import QDConfig
from core.ai.q_assistant import QAssistant

# Load config from the host application
config = QDConfig.from_dict(secrets_dict)

# Initialize assistant
assistant = QAssistant(user_id="user123", org_id="org789", config=config)

# Ask questions
response = assistant.answer_question(
    "What is Python?"
)
```

## Configuration

Axiom uses the `QDConfig` Pydantic model, supporting:
- **TOML files**: For non-sensitive defaults
- **Environment variables**: For secrets and overrides
- **Dependency injection**: For library usage

**Config file search order** (first hit wins):
1. An explicit path argument.
2. `./axiom.toml` (project root / CWD).
3. `~/.config/axiom/axiom.toml`.
4. `~/.config/quantumdrive/axiom.toml`.
5. `./quantumdrive.toml` — deprecated, warns (pre-split basename).
6. `~/.config/quantumdrive/quantumdrive.toml` — deprecated, warns.
7. Packaged default: `core/config/resources/default_axiom.toml`.

A host application (like QuantumDrive) that needs its own basename and its own application-level defaults subclasses `QDConfig`, sets its own `TOML_FILENAME`, and ships its own resource file — that subclass lives in the host's repository, not here.

See [Configuration Guide](docs/reference/Configuration_Guide.md) for complete documentation.

Knowledge graph deployment options:

- Local deployments: leave `AF_KGRAPH.BACKEND="duckdb_sqlite"` for a local `kgraph.duckdb`
- Hosted deployments: set `AF_KGRAPH.BACKEND="postgres"` and provide the Postgres DSN under `[agentfoundry.kgraph.postgres]`, or `"neo4j"` for a Neo4j backend
- GitLab integration: set `AF_GITLAB.BASE_URL`, `AF_GITLAB.USERNAME`, and `AF_GITLAB.TOKEN` to enable the GitLab API tools. Use a personal access token, not an account password.

## Licensing

Axiom enforces a signed license at `core` import time by default.

- `AXIOM_ENFORCE_LICENSE=0` disables enforcement for local development and tests (the deprecated `QUANTUMDRIVE_ENFORCE_LICENSE` spelling still works, with a warning)
- `AXIOM_LICENSE_FILE` overrides the resolved `axiom.lic` path

PQC runtime note:

- Axiom delegates PQC operations to AgentFoundry's `kyber` provider.
- The current runtime stack is pure Python wheels plus native extensions distributed through pip:
  - `pqcrypto`
  - `pycryptodome`
- `liboqs-python` / `oqs` is no longer required for Axiom's PQC and license flows.

Build and packaging flow:

```bash
make install-build-deps
make generate-license DAYS=365 UNBOUND=1
make build
```

The wheel packages `core/axiom.lic` and `core/axiom.pem`, and `core/__init__.py` verifies the license on import.
The bundled license is an unbound trial generated at build time (365 days by default) and can be overridden by placing a different signed `axiom.lic` in a higher-priority lookup location (`~/.config/axiom/`, `~/.config/quantumdrive/`, or the working directory).

**`make release` does not regenerate that license — only `make check-and-release` does.** A plain release reuses whatever `core/axiom.lic` is on disk, which is how 1.0.0 through 1.1.0 all shipped a license that had expired on 2026-07-29. `_check-license` now fails the build when the bundled license has under `LICENSE_MIN_DAYS` (30) left, so run `make generate-license DAYS=365` first when it complains.

### Required Configuration

**Microsoft 365 (QD_* prefix, `core.auth`)**:
- `QD_MS_TENANT_ID` - Microsoft Entra ID tenant
- `QD_MS_CLIENT_ID` - Application client ID
- `QD_MS_CLIENT_SECRET` - Application secret
- `QD_MS_REDIRECT_URI` - OAuth callback URL

**AgentFoundry (AF_* prefix)**:
- `AF_OPENAI_API_KEY` - OpenAI API key
- `AF_LLM_PROVIDER` - LLM provider (openai, ollama, xai)
- `AF_OPENAI_MODEL` - Model name (gpt-5.1, gpt-5.1-codex, etc.)

## Architecture

```
┌─────────────────────────────────────────┐
│    Host application (e.g. QuantumDrive) │
│  - Web application / UI                 │
│  - Secrets management                   │
└──────────────┬──────────────────────────┘
               │ config dict
               ↓
┌─────────────────────────────────────────┐
│              Axiom (AlphaSix IP)         │
│  - Q Assistant                          │
│  - Microsoft 365 integration            │
│  - Vector storage / knowledge graph     │
│  - Configuration bridge                 │
└──────────────┬──────────────────────────┘
               │ AF_* config
               ↓
┌─────────────────────────────────────────┐
│     AgentFoundry (Syntheticore IP)      │
│  - LLM orchestration                    │
│  - Tool registry                        │
│  - Memory management                    │
│  - Vector stores                        │
└─────────────────────────────────────────┘
```

## Components

### Q Assistant (`core/ai/q_assistant.py`)

Conversational AI assistant with:
- Multi-turn conversations with memory
- Tool access (search, calculations, APIs)
- Identity-scoped memory (user, thread, org)
- Crew-based multi-agent workflows

### Microsoft 365 Provider (`core/auth/microsoft_365_provider.py`)

OAuth2 authentication and Graph API access:
- SSO with Microsoft Entra ID
- Token caching and refresh
- User profile retrieval
- Graph API requests

### Configuration (`core/config/`)

Flexible configuration management:
- TOML file loading
- Environment variable overrides
- Dependency injection support
- AgentFoundry config extraction

## Development

### Project Structure

```
axiom/
├── core/
│   ├── ai/              # Q Assistant, agent catalog, prompt library
│   ├── auth/            # Microsoft 365 authentication
│   ├── aws/             # AWS Secrets Manager integration
│   ├── config/          # QDConfig schema and packaged defaults
│   ├── ingest/          # Document processing
│   ├── integrations/    # Connected systems (REST, Postgres, Elasticsearch, ...)
│   ├── kgraph/          # Knowledge graph service facade
│   ├── license/         # PQC-signed license enforcement
│   ├── memory/          # Layered memory (thread/user/org/global)
│   ├── planning/        # Delivery planning and wave execution
│   ├── vectorstore/     # Vector storage service facade
│   └── ...              # See docs/README.md for the full subsystem map
├── docs/                # Documentation
├── scripts/             # Operational one-off scripts
├── tools/               # Build/release tooling (release_version.py, etc.)
└── tests/               # Test suite
```

### Running Tests

```bash
AGENTFOUNDRY_ENFORCE_LICENSE=0 AXIOM_ENFORCE_LICENSE=0 python3 -m pytest tests/
```

### Code Style

```bash
# Format code
black core/ tests/

# Lint
flake8 core/ tests/

# Type check
mypy core/
```

### Branches

Work on a feature branch (`feature/<issue_number>`), open a merge request, and
**delete the branch as soon as it is merged** — both the remote (merge with the
"delete source branch" option) and your local copy (`git branch -d <branch>`).
Merged branches should not linger; keeping the branch list to active work only
makes it obvious what is still in flight. See [AGENTS.md](AGENTS.md) §7 for the
full guideline.

## Documentation

- [Configuration Guide](docs/reference/Configuration_Guide.md) - Complete configuration reference
- [docs/README.md](docs/README.md) - Documentation map

## Security

**Never commit secrets to version control!**

- Use environment variables for API keys and credentials
- Use secrets managers (AWS Secrets Manager, Azure Key Vault) in production
- Add `.env` files to `.gitignore`
- Rotate exposed credentials immediately

## License

Proprietary - AlphaSix IP

## Support

For issues or questions, contact the AlphaSix development team.
