Neurostack Brain

Enterprise AI Intelligence Brain

Neurostack is an AI intelligence layer designed to sit on top of a company's existing systems and make them easier to understand, query, and reason about.

🎯 What Is Neurostack?

Neurostack is not a chatbot, project management tool, or workflow automation platform.

Neurostack is an AI Brain that:

• Reasons over company knowledge (documents, meetings, tasks, decisions)
• Provides accurate, contextual answers
• Respects persona-based access control (employee vs manager)
• Handles uncertainty gracefully
• Operates at enterprise scale

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                     Brain Pipeline                       │
│                                                          │
│  Input → Validate → Classify → Retrieve → Reason → Format │
│         (Stage 1)  (Stage 2)  (Stage 3)  (Stage 4) (Stage 5) │
└─────────────────────────────────────────────────────────┘

Key Properties:
- 2 LLM calls per query (classify + reason)
- Single-pass, deterministic execution
- Batch-friendly, rate-limited safe
- Full audit trail via tracing

Core Components:

1. InputValidator - Validates and normalizes requests
2. IntentClassifier - Classifies user intent (9 types)
3. KnowledgeRetriever - Retrieves from RAG + live context
4. ReasoningEngine - Generates answers with LLM
5. ResponseFormatter - Formats final output
6. BrainOrchestrator - Coordinates full pipeline

See ARCHITECTURE.md for detailed design.

🚀 Quick Start

Installation

# Clone repository
git clone https://github.com/your-org/neurostack-brain.git
cd neurostack-brain

# Install dependencies
pip install -r requirements.txt

# Set up environment
export ANTHROPIC_API_KEY="your-api-key"

Basic Usage

from brain.factory import BrainFactory
from clients.anthropic_llm import AnthropicLLMClient
from clients.mock_vector_store import MockVectorStore
from clients.mock_embedding import SimpleEmbeddingClient

# Initialize clients
llm_client = AnthropicLLMClient(api_key="your-key")
vector_store = MockVectorStore()
embedding_client = SimpleEmbeddingClient(dimension=768)

# Create brain
brain = BrainFactory.create_brain(
    llm_client=llm_client,
    vector_store=vector_store,
    embedding_client=embedding_client
)

# Process query
response = brain.process({
    "query": {
        "user_input": "What is our refund policy?"
    },
    "context": {
        "tenant_id": "company_a",
        "persona": "employee",
        "user_id": "alice@company.com"
    },
    "conversation_history": [],
    "live_context": {},
    "options": {}
})

print(f"Answer: {response.answer.content}")
print(f"Confidence: {response.answer.confidence.value}")

See examples/ for more usage patterns.

📋 Features

✅ Knowledge Types

• Documents (policies, SOPs, manuals)
• Tasks (work items, tickets)
• Meetings (decisions, action items)
• Decisions (finalized outcomes)
• Metrics (KPIs, analytics)
• Events (changes, incidents)
• Facts (distilled truths)

✅ Intent Classification

• Informational queries
• Status queries
• Metrics queries
• Summary requests
• Planning requests
• Task actions
• Decision recall
• Out-of-scope detection

✅ Persona-Based Access Control

• Employee: Personal tasks, public docs
• Manager: Team analytics, multi-person visibility
• Automatic scope enforcement
• Graceful refusal with suggestions

✅ Confidence & Uncertainty

• 3-level confidence model (retrieval, answer, action)
• Conflict detection
• Staleness warnings
• Source attribution
• Reasoning transparency

✅ Memory Architecture

• Short-term: Conversation context (ephemeral)
• Long-term: RAG/vector store (persistent)
• Live context: Current state (injected)

🧪 Testing

# Run all tests
pytest tests/

# Run with coverage
pytest --cov=brain --cov-report=html tests/

# Run specific category
pytest tests/unit/           # Unit tests
pytest tests/integration/    # Integration tests
pytest tests/evaluation/     # Evaluation tests

Test Coverage:

• Unit tests: ~15 tests
• Integration tests: ~12 tests
• Evaluation tests: ~1 test
• Total: ~28 comprehensive tests

See tests/README.md for testing guide.

📚 Documentation

• ARCHITECTURE.md - System design & components
• API_REFERENCE.md - Component APIs
• USAGE_GUIDE.md - How to use the brain
• EVALUATION.md - Quality metrics & calibration

🔧 Configuration

from brain.config.brain_config import BrainConfig, LLMSettings
from brain.config.retrieval_config import RetrieverConfig

config = BrainConfig(
    llm=LLMSettings(
        model="claude-sonnet-4-20250514",
        temperature=0.0,
        max_tokens=1500
    ),
    retrieval=RetrieverConfig(
        default_top_k=10,
        strong_threshold=0.80
    )
)

brain = BrainFactory.create_brain(
    llm_client=llm_client,
    vector_store=vector_store,
    embedding_client=embedding_client,
    config=config  # Custom config
)

All thresholds and parameters are configurable via dataclasses or YAML.

🏢 Production Considerations

Required External Services

1. LLM Client - Claude API (or compatible)
2. Vector Store - Pinecone, Weaviate, Qdrant, etc.
3. Embedding Client - OpenAI, Cohere, etc.

Recommended Infrastructure

• Async Job Queue - For heavy analysis (Celery, RQ)
• Cache Layer - For embeddings and retrieval (Redis)
• Trace Storage - For audit trail (PostgreSQL, Elasticsearch)
• Rate Limiting - External rate limiter (not in brain)

Performance Characteristics

• Latency: ~2-5 seconds per query (2 LLM calls)
• Throughput: Rate-limited by LLM provider
• Memory: ~100-500 MB per brain instance
• Scalability: Stateless, horizontally scalable

🛡️ Design Principles

1. Intelligence over automation - Understanding before action
2. Reasoning over retrieval - Explaining vs fetching
3. Trust over cleverness - Predictable, cautious answers
4. Abstraction over tools - Works regardless of backend systems
5. Incremental adoption - Provides value with partial data

📊 Status

Current Phase: Early validation (tested with ~500 users across multiple companies)

Production Readiness:

• ✅ Core pipeline complete
• ✅ Comprehensive test suite
• ✅ Persona enforcement
• ✅ Error handling
• ⚠️ Async job support (basic implementation)
• ⚠️ Caching layer (deferred)
• ⚠️ Distributed tracing (basic implementation)

🤝 Contributing

Contributions are welcome! Please read our CONTRIBUTING.md first.

Development Setup

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

# Run linting
black src/ tests/
mypy src/
ruff check src/

📝 License

[Your License Here]

🙏 Acknowledgments

Built with:

• Anthropic Claude - LLM reasoning
• Pydantic - Data validation
• pytest - Testing framework

Neurostack - Making enterprise knowledge intelligently accessible. f\x00i\x00x\x00 \x00 \x00