neurostack-org 1.0.0__tar.gz

neurostack_org-1.0.0/PKG-INFO

@@ -0,0 +1,322 @@
+Metadata-Version: 2.4
+Name: neurostack-org
+Version: 1.0.0
+Summary: Enterprise AI SDK — permission-enforced knowledge retrieval across Jira, Slack, Google Docs
+Author: Tauseeq Kazi
+License: BSL-1.1
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: anthropic>=0.40.0
+Requires-Dist: openai>=1.30.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: alembic>=1.13.0
+Requires-Dist: psycopg2-binary>=2.9.0
+Requires-Dist: click>=8.1.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: black>=24.0.0; extra == "dev"
+Requires-Dist: mypy>=1.8.0; extra == "dev"
+Requires-Dist: ruff>=0.2.0; extra == "dev"
+Provides-Extra: qdrant
+Requires-Dist: qdrant-client>=1.7.0; extra == "qdrant"
+Provides-Extra: pinecone
+Requires-Dist: pinecone-client>=3.0.0; extra == "pinecone"
+Provides-Extra: google
+Requires-Dist: google-auth>=2.0.0; extra == "google"
+Requires-Dist: google-auth-oauthlib>=1.0.0; extra == "google"
+Requires-Dist: google-api-python-client>=2.80.0; extra == "google"
+Provides-Extra: encryption
+Requires-Dist: cryptography>=41.0.0; extra == "encryption"
+
+# 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](docs/architecture.md) for detailed design.
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+# 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
+
+```python
+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/](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
+
+```bash
+# 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](tests/README.md) for testing guide.
+
+## 📚 Documentation
+
+- [ARCHITECTURE.md](docs/architecture.md) - System design & components
+- [API_REFERENCE.md](docs/api_reference.md) - Component APIs
+- [USAGE_GUIDE.md](docs/usage_guide.md) - How to use the brain
+- [EVALUATION.md](docs/evaluation.md) - Quality metrics & calibration
+
+## 🔧 Configuration
+
+```python
+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](CONTRIBUTING.md) first.
+
+### Development Setup
+
+```bash
+# 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](https://anthropic.com) - LLM reasoning
+- [Pydantic](https://pydantic.dev) - Data validation
+- [pytest](https://pytest.org) - Testing framework
+
+---
+
+**Neurostack** - Making enterprise knowledge intelligently accessible.
+fix
+
+

neurostack_org-1.0.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "neurostack-org"
+version = "1.0.0"
+description = "Enterprise AI SDK — permission-enforced knowledge retrieval across Jira, Slack, Google Docs"
+authors = [{name = "Tauseeq Kazi"}]
+license = {text = "BSL-1.1"}
+readme = "README.md"
+requires-python = ">=3.11"
+
+dependencies = [
+    "anthropic>=0.40.0",
+    "openai>=1.30.0",
+    "pydantic>=2.0.0",
+    "pyyaml>=6.0",
+    "alembic>=1.13.0",
+    "psycopg2-binary>=2.9.0",
+    "click>=8.1.0",
+    "rich>=13.0.0",
+    "httpx>=0.25.0",
+]
+
+[project.scripts]
+neurostack = "pipeline.cli.main:cli"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+    "pytest-asyncio>=0.23.0",
+    "black>=24.0.0",
+    "mypy>=1.8.0",
+    "ruff>=0.2.0",
+]
+qdrant = ["qdrant-client>=1.7.0"]
+pinecone = ["pinecone-client>=3.0.0"]
+google = [
+    "google-auth>=2.0.0",
+    "google-auth-oauthlib>=1.0.0",
+    "google-api-python-client>=2.80.0",
+]
+encryption = ["cryptography>=41.0.0"]
+
+# 🔑 THIS MAKES `brain` IMPORTABLE
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# Tooling
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.black]
+line-length = 100
+target-version = ["py311"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_return_any = true
+warn_unused_configs = true

neurostack_org-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

neurostack_org-1.0.0/src/brain/config/brain_config.py

@@ -0,0 +1,75 @@
+"""
+Main brain configuration.
+
+Dataclasses are source of truth. YAML loading is optional convenience.
+"""
+
+from dataclasses import dataclass, field
+from typing import Dict, Optional
+import yaml
+
+from .retrieval_config import RetrieverConfig
+from .confidence_config import ConfidenceConfig
+from .persona_config import PersonaConfig
+
+
+@dataclass
+class LLMSettings:
+    """LLM client settings"""
+    model: str = "claude-sonnet-4-20250514"
+    temperature: float = 0.0
+    max_tokens: int = 1000
+    timeout_seconds: int = 30
+
+
+@dataclass
+class ConversationSettings:
+    """Conversation management settings"""
+    max_history_turns: int = 5  # Last N turns to include
+    max_history_tokens: int = 2000  # Approximate token budget for history
+
+
+
+
+@dataclass
+class BrainConfig:
+    """
+    Main brain configuration.
+    
+    All components receive config from this root object.
+    """
+    
+    # Component configs
+    llm: LLMSettings = field(default_factory=LLMSettings)
+    retrieval: RetrieverConfig = field(default_factory=RetrieverConfig)
+    confidence: ConfidenceConfig = field(default_factory=ConfidenceConfig)
+    persona: PersonaConfig = field(default_factory=PersonaConfig)
+    conversation: ConversationSettings = field(default_factory=ConversationSettings)
+    
+    @classmethod
+    def default(cls) -> "BrainConfig":
+        """Create config with all defaults"""
+        return cls()
+    
+    @classmethod
+    def from_yaml(cls, path: str) -> "BrainConfig":
+        """
+        Load config from YAML file.
+        
+        YAML structure should mirror dataclass hierarchy.
+        """
+        with open(path, 'r') as f:
+            data = yaml.safe_load(f)
+        
+        return cls(
+            llm=LLMSettings(**data.get('llm', {})),
+            retrieval=RetrieverConfig.from_dict(data.get('retrieval', {})),
+            confidence=ConfidenceConfig.from_dict(data.get('confidence', {})),
+            persona=PersonaConfig.from_dict(data.get('persona', {})),
+            conversation=ConversationSettings(**data.get('conversation', {}))
+        )
+    
+    def to_yaml(self, path: str) -> None:
+        """Export config to YAML file"""
+        # Implementation for config export
+        pass

neurostack_org-1.0.0/src/brain/config/confidence_config.py

@@ -0,0 +1,79 @@
+"""
+Confidence assessment configuration.
+"""
+
+from dataclasses import dataclass, field
+from typing import Dict
+
+
+@dataclass
+class ActionConfidenceThresholds:
+    """Confidence thresholds per action type (risk-adjusted)"""
+    
+    # Low risk actions (can execute without confirmation)
+    low_risk_threshold: float = 0.85
+    low_risk_actions: list = field(default_factory=lambda: [
+        "assign_task",
+        "add_comment",
+        "update_description"
+    ])
+    
+    # Medium risk actions (require confirmation)
+    medium_risk_threshold: float = 0.90
+    medium_risk_actions: list = field(default_factory=lambda: [
+        "update_status",
+        "change_priority",
+        "reassign_task"
+    ])
+    
+    # High risk actions (require strong confirmation)
+    high_risk_threshold: float = 0.95
+    high_risk_actions: list = field(default_factory=lambda: [
+        "delete_task",
+        "archive_project",
+        "remove_user"
+    ])
+    
+    def get_threshold(self, action_type: str) -> float:
+        """Get threshold for specific action type"""
+        if action_type in self.low_risk_actions:
+            return self.low_risk_threshold
+        elif action_type in self.medium_risk_actions:
+            return self.medium_risk_threshold
+        elif action_type in self.high_risk_actions:
+            return self.high_risk_threshold
+        else:
+            return self.medium_risk_threshold  # Default to medium
+
+
+@dataclass
+class ConfidenceConfig:
+    """Configuration for confidence assessment"""
+    
+    # Retrieval confidence thresholds
+    retrieval_strong_threshold: float = 0.75
+    retrieval_acceptable_threshold: float = 0.60
+    retrieval_dominance_gap: float = 0.15
+    
+    # Answer confidence rules
+    # (These are used in decision matrix logic, not hardcoded thresholds)
+    
+    # Confidence upgrade limits
+    max_upgrade_from_clarification: int = 1  # Max levels to upgrade
+    
+    # Action confidence
+    action_thresholds: ActionConfidenceThresholds = field(
+        default_factory=ActionConfidenceThresholds
+    )
+    
+    # Conflict handling
+    conflict_always_caps_at_uncertain: bool = True
+    
+    @classmethod
+    def from_dict(cls, data: dict) -> "ConfidenceConfig":
+        """Create from dictionary"""
+        action_data = data.pop('action_thresholds', {})
+        return cls(
+            action_thresholds=ActionConfidenceThresholds(**action_data),
+            **data
+        )

neurostack_org-1.0.0/src/brain/config/persona_config.py

@@ -0,0 +1,50 @@
+"""
+Persona configuration and rules.
+"""
+
+from dataclasses import dataclass, field
+from typing import Dict, List
+
+
+@dataclass
+class PersonaConfig:
+    """Configuration for persona enforcement"""
+    
+    # Employee restrictions
+    employee_allowed_scopes: List[str] = field(default_factory=lambda: [
+        "personal",
+        "public"
+    ])
+    
+    employee_forbidden_intents: List[str] = field(default_factory=lambda: [
+        "metrics_query",  # When scope = team
+        "planning_request"  # When scope = team
+    ])
+    
+    # Manager permissions
+    manager_allowed_scopes: List[str] = field(default_factory=lambda: [
+        "personal",
+        "public",
+        "team"
+    ])
+    
+    # Ethical constraints (apply to all personas)
+    forbidden_query_patterns: List[str] = field(default_factory=lambda: [
+        "performance_comparison",  # "Who is slower, Alice or Bob?"
+        "surveillance_tracking",   # "How many hours did X work?"
+        "punitive_metrics"         # "Show me underperformers"
+    ])
+    
+    # Scope detection keywords
+    team_scope_keywords: List[str] = field(default_factory=lambda: [
+        "team", "our", "we", "everyone", "all", "group"
+    ])
+    
+    personal_scope_keywords: List[str] = field(default_factory=lambda: [
+        "my", "I", "me", "mine"
+    ])
+    
+    @classmethod
+    def from_dict(cls, data: dict) -> "PersonaConfig":
+        """Create from dictionary"""
+        return cls(**data)

neurostack_org-1.0.0/src/brain/config/retrieval_config.py

@@ -0,0 +1,23 @@
+from dataclasses import dataclass, field
+from typing import Dict
+
+
+@dataclass
+class RetrieverConfig:
+    """Retrieval configuration"""
+    
+    # Retrieval depth
+    default_top_k: int = 5
+    max_top_k: int = 20  # hard cap
+    
+    # Confidence thresholds (relative)
+    strong_threshold: float = 0.75
+    acceptable_threshold: float = 0.60
+    dominance_gap: float = 0.15
+    recency_boost_factor: float = 0.1
+    # Authority weights
+    authority_weights: dict = field(default_factory=lambda: {
+        "high": 1.2,
+        "medium": 1.0,
+        "low": 0.8
+    })

neurostack_org-1.0.0/src/brain/core/__init__.py

@@ -0,0 +1,21 @@
+"""
+Core brain components.
+
+These components form the reasoning pipeline.
+"""
+
+from .input_validator import InputValidator
+from .intent_classifier import IntentClassifier
+from .knowledge_retriever import KnowledgeRetriever
+from .reasoning_engine import ReasoningEngine
+from .response_formatter import ResponseFormatter
+from .orchestrator import BrainOrchestrator
+
+__all__ = [
+    'InputValidator',
+    'IntentClassifier',
+    'KnowledgeRetriever',
+    'ReasoningEngine',
+    'ResponseFormatter',
+    'BrainOrchestrator',
+]