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:

   pip install -r requirements.txt
   

   For packaging, license generation, and PQC-related tests, install the build extras:

   make install-build-deps
   

2. Create configuration (choose one):

   Option A: Project root (for development):

   cp core/config/resources/default_axiom.toml axiom.toml
   

   Option B: User config directory (for production):

   mkdir -p ~/.config/axiom
   cp core/config/resources/default_axiom.toml ~/.config/axiom/axiom.toml
   

3. Set environment variables:

   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:

   make generate-keys                      # one-time: vendor signing keypair
   make generate-license DAYS=365 UNBOUND=1
   

5. Verify the install:

   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)

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 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:

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

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

Code Style

# 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 §7 for the full guideline.

Documentation

• Configuration Guide - Complete configuration reference
• 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.